file_dump_listener.h File Reference

The listener creates a new file and stores all the incomming events in it. More...

#include <hawktracer/timeline.h>
#include <stdio.h>

Go to the source code of this file.

Typedefs
typedef typedefHT_DECLS_BEGIN struct _HT_FileDumpListener	HT_FileDumpListener

Functions
HT_API HT_FileDumpListener *	ht_file_dump_listener_register (HT_Timeline *timeline, const char *filename, size_t buffer_size, HT_ErrorCode *out_err)
	Creates a file dump listener and registers it to a timeline. More...
HT_API HT_FileDumpListener *	ht_file_dump_listener_create (const char *filename, size_t buffer_size, HT_ErrorCode *out_err)
	Creates an instance of a file dump listener. More...
HT_API void	ht_file_dump_listener_destroy (HT_FileDumpListener *listener)
	Destroys an instance of the listener. More...
HT_API void	ht_file_dump_listener_callback (TEventPtr events, size_t size, HT_Boolean serialized, void *user_data)
	A listener callback. More...
HT_API HT_ErrorCode	ht_file_dump_listener_flush (HT_FileDumpListener *listener, HT_Boolean flush_stream)
	Flushes internal listener buffer. More...
HT_API void	ht_file_dump_listener_stop (HT_FileDumpListener *listener)
	Stops listening to new events. More...

Detailed Description

The listener creates a new file and stores all the incomming events in it.

The listener can handle both serialized and unserialized event streams.

Typedef Documentation

HT_FileDumpListener

typedef typedefHT_DECLS_BEGIN struct _HT_FileDumpListener HT_FileDumpListener

Function Documentation

ht_file_dump_listener_callback()

HT_API void ht_file_dump_listener_callback	(	TEventPtr	events,
		size_t	size,
		HT_Boolean	serialized,
		void *	user_data
	)

A listener callback.

This callback should be used for the ht_timeline_register_listener() function.

ht_file_dump_listener_create()

HT_API HT_FileDumpListener* ht_file_dump_listener_create	(	const char *	filename,
		size_t	buffer_size,
		HT_ErrorCode *	out_err
	)

Creates an instance of a file dump listener.

Internal buffer can be disabled by setting buffer_size parameter to 0. However, the internal buffer must not be disabled if event stream is not serialized - this setting causes undefined behavior.

Parameters

filename	a name of the file to store the data in.
buffer_size	a size of the internal buffer.
out_err	a pointer to an error code variable where the error will be stored if the operation fails.

Returns

a pointer to a new instance of the listener.

ht_file_dump_listener_destroy()

HT_API void ht_file_dump_listener_destroy

(

HT_FileDumpListener *

listener

)

Destroys an instance of the listener.

Parameters

listener

a pointer to the listener to be destroyed.

ht_file_dump_listener_flush()

HT_API HT_ErrorCode ht_file_dump_listener_flush	(	HT_FileDumpListener *	listener,
		HT_Boolean	flush_stream
	)

Flushes internal listener buffer.

The listener is normally flushed when the internal buffer is full or when ht_file_dump_listener_destroy() is called. However, user might want to forcefully flush the data into a file if needed using this function.

Parameters

listener	a pointer to the listener.
flush_stream	HT_TRUE if the function should also flush internal FILE buffer; if not, set to HT_FALSE

Returns

HT_ERR_OK if the operation completed successfully; otherwise, appropriate error code is returned. This function can potentially fail only if flush_stream parameter is set to HT_TRUE.

ht_file_dump_listener_register()

HT_API HT_FileDumpListener* ht_file_dump_listener_register	(	HT_Timeline *	timeline,
		const char *	filename,
		size_t	buffer_size,
		HT_ErrorCode *	out_err
	)

Creates a file dump listener and registers it to a timeline.

This is a helper function that wrapps ht_file_dump_listener_create() and ht_timeline_register_listener_full(). The user can achieve the same result by explicitly creating a listener and registering it to a timeline:

HT_FileDumpListener* listener = ht_file_dump_listener_create("file.htdump", 2048, &error_code);
ht_timeline_register_listener_full(
            timeline,
            ht_file_dump_listener_callback,
            listener,
            (HT_DestroyCallback)ht_file_dump_listener_destroy);

Please note the example above doesn't implement error handling, which would make the code even more complicated.

Parameters

timeline	the timeline where the listener will be attached to.
filename	a name of the file to store the data in.
buffer_size	a size of the internal buffer.
out_err	a pointer to an error code variable where the error will be stored if the operation fails.

Returns

a pointer to a new instance of the listener.

ht_file_dump_listener_stop()

HT_API void ht_file_dump_listener_stop

(

HT_FileDumpListener *

listener

)

Stops listening to new events.

The function is very similar to ht_file_dump_listener_destroy() except it does not release the memory allocated for listener object. After stopping the listener, there's no way to resume it. User needs to create another listener and register it for the timeline instead.

Parameters

listener

the listener.