#include <hawktracer/events.h>
#include <hawktracer/monotonic_clock.h>
#include <hawktracer/timeline_listener.h>
#include <hawktracer/event_id_provider.h>
#include <hawktracer/feature.h>
#include <stddef.h>

Macros
#define	HT_TIMELINE_FEATURE(timeline, feature_id, feature_type) ((feature_type*)ht_timeline_get_feature(timeline, feature_id))
	Returns a pointer to a timeline's feature. More...

#define	HT_TIMELINE_MAX_FEATURES 32
	Defines maximum number of features that can be attached to a timeline. More...

#define	HT_TIMELINE_PUSH_EVENT(TIMELINE, EVENT_TYPE, ...) HT_TIMELINE_PUSH_EVENT_PEDANTIC(TIMELINE, EVENT_TYPE, ht_base_event, __VA_ARGS__)
	Pushes an event to the timeline. More...

#define	HT_TIMELINE_PUSH_EVENT_PEDANTIC(TIMELINE, EVENT_TYPE, ...)
	Pushes an event to the timeline. More...

Typedefs
typedef typedefHT_DECLS_BEGIN struct _HT_Timeline	HT_Timeline

Functions
HT_API HT_Timeline *	ht_timeline_create (size_t buffer_capacity, HT_Boolean thread_safe, HT_Boolean serialize_events, const char listeners, HT_ErrorCode out_err)

HT_API void	ht_timeline_destroy (HT_Timeline *timeline)
	Destroys a timeline. More...

HT_API HT_ErrorCode	ht_timeline_register_listener (HT_Timeline timeline, HT_TimelineListenerCallback callback, void user_data)
	Registers new listener to a timeline. More...

HT_API HT_ErrorCode	ht_timeline_register_listener_full (HT_Timeline timeline, HT_TimelineListenerCallback callback, void user_data, HT_DestroyCallback destroy_callback)
	Registers new listener to a timeline. More...

HT_API void	ht_timeline_unregister_all_listeners (HT_Timeline *timeline)
	Removes all the listeners from a timeline. More...

HT_API void	ht_timeline_init_event (HT_Timeline timeline, HT_Event event)
	Initializes event according to timeline's parameters. More...

HT_API void	ht_timeline_push_event (HT_Timeline timeline, HT_Event event)
	Pushes an event to a timeline. More...

HT_API void	ht_timeline_flush (HT_Timeline *timeline)
	Transfers all the events from internal buffer to listeners. More...

HT_API HT_ErrorCode	ht_timeline_set_feature (HT_Timeline timeline, HT_Feature feature)
	Enables a specific feature in the timeline. More...

HT_API HT_Feature *	ht_timeline_get_feature (HT_Timeline timeline, HT_FeatureKlass feature_klass)
	Gets the feature object of a specific class from the pipeline. More...

HT_API HT_EventIdProvider *	ht_timeline_get_id_provider (HT_Timeline *timeline)

Macro Definition Documentation

◆ HT_TIMELINE_FEATURE

#define HT_TIMELINE_FEATURE	(	timeline,
		feature_id,
		feature_type
	)	((feature_type*)ht_timeline_get_feature(timeline, feature_id))

Returns a pointer to a timeline's feature.

◆ HT_TIMELINE_MAX_FEATURES

#define HT_TIMELINE_MAX_FEATURES 32

Defines maximum number of features that can be attached to a timeline.

◆ HT_TIMELINE_PUSH_EVENT

#define HT_TIMELINE_PUSH_EVENT	(	TIMELINE,
		EVENT_TYPE,
		...
	)	HT_TIMELINE_PUSH_EVENT_PEDANTIC(TIMELINE, EVENT_TYPE, ht_base_event, __VA_ARGS__)

Pushes an event to the timeline.

The macro automatically constructs the event, so user only needs to specify values for event fields (excluding values for HT_Event; i.e. timestamp, event_id and klass_id).

Parameters

TIMELINE	the timeline.
EVENT_TYPE	a type of the event to push.
...	a list of parameters of the event.

◆ HT_TIMELINE_PUSH_EVENT_PEDANTIC

#define HT_TIMELINE_PUSH_EVENT_PEDANTIC	(	TIMELINE,
		EVENT_TYPE,
		...
	)

Value:

do { \
        HT_Event ht_base_event = { \
            ht_##EVENT_TYPE##_get_event_klass_instance(), \
            ht_monotonic_clock_get_timestamp(), \
            ht_event_id_provider_next(ht_timeline_get_id_provider(TIMELINE)) \
        }; \
        EVENT_TYPE ev = {__VA_ARGS__}; \
        ht_timeline_push_event(TIMELINE, HT_EVENT(&ev)); \
    } while (0)

Pushes an event to the timeline.

The difference between this macro and HT_TIMELINE_PUSH_EVENT() is that it requires using curly brackets for sub-events. It provides a special variable ht_base_event that represents the HT_Event base instance. For example, to push SubEvent to a timeline, you should do:

struct SubEvent {
  HT_Event base;
  int field1;
  float field2;
};
HT_TIMELINE_PUSH_EVENT_PEDANTIC(timeline, SubEvent, {{ht_base_event}, 3, 9.3f});

The macro allows you to push events without generating compiler warnings (unlike HT_TIMELINE_PUSH_EVENT()).

Parameters

TIMELINE	the timeline.
EVENT_TYPE	a type of the event to push.
...	a list of parameters of the event.

Typedef Documentation

◆ HT_Timeline

typedef typedefHT_DECLS_BEGIN struct _HT_Timeline HT_Timeline

Function Documentation

◆ ht_timeline_create()

HT_API HT_Timeline* ht_timeline_create	(	size_t	buffer_capacity,
		HT_Boolean	thread_safe,
		HT_Boolean	serialize_events,
		const char *	listeners,
		HT_ErrorCode *	out_err
	)

◆ ht_timeline_destroy()

HT_API void ht_timeline_destroy ( HT_Timeline * timeline )

Destroys a timeline.

Parameters

timeline a pointer to the timeline to destroy.

◆ ht_timeline_flush()

HT_API void ht_timeline_flush ( HT_Timeline * timeline )

Transfers all the events from internal buffer to listeners.

Parameters

timeline the timeline.

◆ ht_timeline_get_feature()

HT_API HT_Feature* ht_timeline_get_feature	(	HT_Timeline *	timeline,
		HT_FeatureKlass *	feature_klass
	)

Gets the feature object of a specific class from the pipeline.

Parameters

timeline	the timeline.
feature_klass	the feature class.

Returns: a feature object of the specific class, if the timeline has the feature of this class enabled; otherwise, NULL.

◆ ht_timeline_get_id_provider()

HT_API HT_EventIdProvider* ht_timeline_get_id_provider ( HT_Timeline * timeline )

◆ ht_timeline_init_event()

HT_API void ht_timeline_init_event	(	HT_Timeline *	timeline,
		HT_Event *	event
	)

Initializes event according to timeline's parameters.

The method sets a timestamp and event_id for the event.

Parameters

timeline	the timeline.
event	the event to initialize.

◆ ht_timeline_push_event()

HT_API void ht_timeline_push_event	(	HT_Timeline *	timeline,
		HT_Event *	event
	)

Pushes an event to a timeline.

Parameters

timeline	the timeline.
event	the event.

◆ ht_timeline_register_listener()

HT_API HT_ErrorCode ht_timeline_register_listener	(	HT_Timeline *	timeline,
		HT_TimelineListenerCallback	callback,
		void *	user_data
	)

Registers new listener to a timeline.

Parameters

timeline	the timeline.
callback	a callback of the listener.
user_data	additional data that will be passed to the listener's callback.

Returns: HT_ERR_OK if registration completed successfully; otherwise, error code.

Deprecated:: use ht_timeline_register_listener_full() instead.

◆ ht_timeline_register_listener_full()

HT_API HT_ErrorCode ht_timeline_register_listener_full	(	HT_Timeline *	timeline,
		HT_TimelineListenerCallback	callback,
		void *	user_data,
		HT_DestroyCallback	destroy_callback
	)

Registers new listener to a timeline.

The timeline will call destroy_callback callback to destroy user_data value when it is no longer needed, so the user must not free user_data, unless the value of destroy_callback is NULL - in that case, no destroy callback will be called.

Parameters

timeline	the timeline.
callback	a callback of the listener.
user_data	additional data that will be passed to the listener's callback.
destroy_callback	functor called when user_data is no longer needed.

Returns: HT_ERR_OK if registration completed successfully; otherwise, error code.

◆ ht_timeline_set_feature()

HT_API HT_ErrorCode ht_timeline_set_feature	(	HT_Timeline *	timeline,
		HT_Feature *	feature
	)

Enables a specific feature in the timeline.

The timeline takes ownership of the feature, it means it will automatically destroys it during timeline's destruction. The timeline can have multiple features enabled, but it's not possible to enable the same feature twice (second attempt results with HT_ERR_FEATURE_ALREADY_REGISTERED error code). Before enabling the feature for the timeline, the feature must be registered. If it's not, the function returns HT_ERR_FEATURE_NOT_REGISTERED error code.

Parameters

timeline	the timeline.
feature	the feature.

Returns: HT_ERR_OK if enabling the feature completed successfully; otherwise, error code.

◆ ht_timeline_unregister_all_listeners()

HT_API void ht_timeline_unregister_all_listeners ( HT_Timeline * timeline )

Removes all the listeners from a timeline.

Parameters

timeline the timeline.

Deprecated:: HawkTracer no longer allows unregistering listeners. However, the common pattern is to "stop" the listener; i.e. release all the resources held by listener and start ignoring all the incoming events. See ht_file_dump_listener_stop() for the example.

Macros

Typedefs

Functions

Macro Definition Documentation

◆ HT_TIMELINE_FEATURE

◆ HT_TIMELINE_MAX_FEATURES

◆ HT_TIMELINE_PUSH_EVENT

◆ HT_TIMELINE_PUSH_EVENT_PEDANTIC

Typedef Documentation

◆ HT_Timeline

Function Documentation

◆ ht_timeline_create()

◆ ht_timeline_destroy()

◆ ht_timeline_flush()

◆ ht_timeline_get_feature()

◆ ht_timeline_get_id_provider()

◆ ht_timeline_init_event()

◆ ht_timeline_push_event()

◆ ht_timeline_register_listener()

◆ ht_timeline_register_listener_full()

◆ ht_timeline_set_feature()

◆ ht_timeline_unregister_all_listeners()