Functions and data structures for eventing. More...

#include "util/mem.h"
#include "util/workq.h"

Data Structures
struct	_jw_event_data_t

Typedefs
typedef struct _jw_event_dispatch_t	jw_event_dispatcher

typedef struct _jw_event_t	jw_event

typedef struct _jw_event_trigger_t	jw_event_trigger_data

typedef struct _jw_event_data_t *	jw_event_data

typedef void(*	jw_event_notify_callback) (jw_event_data evt, void *arg)

typedef void(*	jw_event_result_callback) (jw_event_data evt, bool result, void *arg)

Functions
JABBERWERX_API bool	jw_event_dispatcher_create (void source, jw_workq workq, jw_event_dispatcher *dispatch, jw_err err)

JABBERWERX_API void	jw_event_dispatcher_destroy (jw_event_dispatcher *dispatch)

JABBERWERX_API jw_workq *	jw_event_dispatcher_get_workq (jw_event_dispatcher *dispatch)

JABBERWERX_API jw_event *	jw_event_dispatcher_get_event (jw_event_dispatcher dispatch, const char name)

JABBERWERX_API bool	jw_event_dispatcher_create_event (jw_event_dispatcher dispatch, const char name, jw_event *event, jw_err err)

JABBERWERX_API const char *	jw_event_get_name (jw_event *event)

JABBERWERX_API const void *	jw_event_get_source (jw_event *event)

JABBERWERX_API bool	jw_event_bind (jw_event event, jw_event_notify_callback cb, void arg, jw_err *err)

JABBERWERX_API void	jw_event_unbind (jw_event *event, jw_event_notify_callback cb)

JABBERWERX_API bool	jw_event_trigger (jw_event event, void data, jw_event_result_callback result_cb, void result_arg, jw_err err)

JABBERWERX_API void	jw_event_trigger_prepared (jw_event event, void data, jw_event_result_callback result_cb, void result_arg, jw_event_trigger_data trigger_data)

JABBERWERX_API bool	jw_event_prepare_trigger (jw_event_dispatcher dispatch, jw_event_trigger_data trigger_data, jw_err err)

JABBERWERX_API void	jw_event_unprepare_trigger (jw_event_trigger_data *trigger_data)

Detailed Description

Functions and data structures for eventing.

Each source that generates events SHOULD export a <source_type>_event function that returns a named event, or NULL if it does not exist.

jw_event <source_type>_event(<source_type> source, const char *name)

The name should match lexically in an ASCII case-insensitive manner.

Copyrights

Typedef Documentation

typedef struct _jw_event_t jw_event

Datatype for an event (notifier). It manages the callbacks and triggerings for a given event.

typedef struct _jw_event_data_t * jw_event_data

Event data passed to bound callbacks.

typedef struct _jw_event_dispatch_t jw_event_dispatcher

Datatype for an event dispatcher. Each event source contains an event dispatcher. It creates and manages events, and regulates any event triggerings for its owned events.

typedef void(* jw_event_notify_callback) (jw_event_data evt, void *arg)

Callback executed when an event is triggered. Callbacks should set the handled flag in the jw_event_data to true to indicate the event was handled.

Parameters

[in]	evt	Event information
[in]	arg	An argument bound to this callback

typedef void(* jw_event_result_callback) (jw_event_data evt, bool result, void *arg)

Callback executed when an event triggering is complete.

Parameters

[in]	evt	Event information
[in]	result	True if any notify callbacks returned true, false otherwise
[in]	arg	The user-provided data when the event was triggered

typedef struct _jw_event_trigger_t jw_event_trigger_data

Data used by an event trigger.

Function Documentation

JABBERWERX_API bool jw_event_bind	(	jw_event *	event,
		jw_event_notify_callback	cb,
		void *	arg,
		jw_err *	err
	)

Binds the given callback to the event.

NOTE: Callbacks are unique by their pointer reference. Registering the same function multiple times has no effect and will not change binding list position.

This function can generate the following errors (set when returning false):

JW_ERR_NO_MEMORY if the binding could not be allocated

Invariant: event != NULL; cb != NULL

Parameters

[in]	event	The event
[in]	cb	The callback to execute when the event is triggered
[in]	arg	User-provided data for the callback
[out]	err	The error information (provide NULL to ignore)

Return values

bool	True if the callback was successfully bound.

JABBERWERX_API bool jw_event_dispatcher_create	(	void *	source,
		jw_workq *	workq,
		jw_event_dispatcher **	dispatch,
		jw_err *	err
	)

Creates a new jw_event_dispatcher for the given source. Depending on the value of the workq parameter, the dispatcher can be synchronous (events fire before a call to trigger returns) or asynchronous (events are enqueued on a workq and fire from the libevent event queue).

This function can generate the following errors (set when returning false):

JW_ERR_NO_MEMORY if the dispatcher could not be allocated

Invariant: source != NULL; dispatch != NULL

Parameters

[in]	source	The event source
[in]	workq	The work queue. If NULL, the dispatcher will be synchronous, if non-NULL, asynchronous
[out]	dispatch	The created event dispatcher
[out]	err	The error information (provide NULL to ignore)

Return values

bool	True if the dispatcher was created successfully.

JABBERWERX_API bool jw_event_dispatcher_create_event	(	jw_event_dispatcher *	dispatch,
		const char *	name,
		jw_event **	event,
		jw_err *	err
	)

Create a new event for the given dispatcher and event name. When created, this event is registered with the given dispatcher and can be accessed via jw_event_dispatcher_get_event().

NOTE: The event name is case-insensitive; while the original value may be retained, most uses use a "lower-case" variant. NOTE: The event name is assumed to be ASCII letters and numbers; no attempt is made to validate or enforce this restriction

This function can generate the following errors (set when returning false):

JW_ERR_NO_MEMORY if the event could not be allocated
JW_ERR_INVALID_ARG if {name} is the empty string
JW_ERR_INVALID_STATE if an event for {name} already exists in {dispatch}

Invariant: dispatch != NULL; name != NULL

Parameters

[in]	dispatch	The owning event dispatcher
[in]	name	The event name
[out]	event	The created event (provide NULL to ignore)
[out]	err	The error information (provide NULL to ignore)

Return values

bool	True if the event was created successfully.

JABBERWERX_API void jw_event_dispatcher_destroy ( jw_event_dispatcher * dispatch )

Destroys the given dispatcher and frees its resources. If the handler for an event is currently running, the destruction is deferred until the handler returns.

NOTE: Any remaining scheduled event handlers will not execute.

Invariant: dispatch != NULL

Parameters

[in] dispatch The event dispatcher

JABBERWERX_API jw_event* jw_event_dispatcher_get_event	(	jw_event_dispatcher *	dispatch,
		const char *	name
	)

Retrieves the event notifier from the dispatcher for the given name. Events are matched using an ASCII case-insensitive lookup.

Invariant: dispatch != NULL; name != NULL

Parameters

[in]	dispatch	The event dispatcher
[in]	name	The event name

Return values

jw_event_notifier The event notifier, or NULL if not found

JABBERWERX_API jw_workq* jw_event_dispatcher_get_workq ( jw_event_dispatcher * dispatch )

Retrieves the workq used by the given dispatcher.

Invariant: dispatch != NULL

Parameters

[in] dispatch The event dispatcher

Return values

jw_workq The workq used by the dispatcher

JABBERWERX_API const char* jw_event_get_name ( jw_event * event )

Retrieves the name of this event. The value returned by this function is owned by the event, and its memory is released when the event is destroyed.

Invariant: event != NULL

Parameters

[in] event The event

Return values

const char * The name of the event

JABBERWERX_API const void* jw_event_get_source ( jw_event * event )

Retrieves the source for the given event.

Invariant: event != NULL

Parameters

[in] event The event

Return values

void	* The event source

JABBERWERX_API bool jw_event_prepare_trigger	(	jw_event_dispatcher *	dispatch,
		jw_event_trigger_data **	trigger_data,
		jw_err *	err
	)

Pre-allocates the data structures for a single call to jw_event_trigger_prepared.

This function can generate the following errors (set when returning false):

JW_ERR_NO_MEMORY if the triggering info could not be allocated

Invariant: trigger_data != NULL

Parameters

[in]	dispatch	The event dispatcher
[out]	trigger_data	The created structure
[out]	err	The error information (provide NULL to ignore)

Return values

bool	True if the structures were successfully allocated

JABBERWERX_API bool jw_event_trigger	(	jw_event *	event,
		void *	data,
		jw_event_result_callback	result_cb,
		void *	result_arg,
		jw_err *	err
	)

Fires an event on all registered callbacks, with the given data. Triggered events are handled in a "breadth-first" fashion; events triggered within an event callback are added to an event queue and processed when the triggering callback returns. Each source has its own event queue.

This function can generate the following errors (set when returning false):

JW_ERR_NO_MEMORY if the triggering info could not be allocated

Invariant: event != NULL

Parameters

[in]	event	The event
[in]	data	The data for this event triggering
[in]	result_cb	Callback to receive trigger result
[in]	result_arg	User-specific data for result_cb
[out]	err	The error information (provide NULL to ignore)

Return values

bool	True if the callback was successfully bound.

JABBERWERX_API void jw_event_trigger_prepared	(	jw_event *	event,
		void *	data,
		jw_event_result_callback	result_cb,
		void *	result_arg,
		jw_event_trigger_data *	trigger_data
	)

Same as jw_event_trigger except that no internal allocation takes place, ensuring the trigger succeeds, even in low memory conditions.

Invariant: event != NULL; trigger_data != NULL

Parameters

[in]	event	The event
[in]	data	The data for this event triggering
[in]	result_cb	Callback to receive trigger result
[in]	result_arg	User-specific data for result_cb
[in]	trigger_data	The preallocated structures to use for the callback. This will be cleaned up by the triggering mechanism.

JABBERWERX_API void jw_event_unbind	(	jw_event *	event,
		jw_event_notify_callback	cb
	)

Unbinds the given event callback. If {cb} is not currently bound to the event, this function does nothing.

Invariant: event != NULL; cb != NULL

Parameters

[in]	event	The event
[in]	cb	The callback to unbind

JABBERWERX_API void jw_event_unprepare_trigger ( jw_event_trigger_data * trigger_data )

Destroys unused trigger data. Trigger data is normally destroyed by jw_event_trigger_prepared(), but this call is provided for the case where trigger data is prepared but the prepared event is never triggered.

Invariant: trigger_data != NULL

Parameters

[in] trigger_data The structure to be destroyed

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation