event.h File Reference

sc_callback: Interface for event notification. More...

#include <sys/epoll.h>

Data Structures
struct	sc_callback
	A callback object. More...

Typedefs
typedef void(	sc_callback_handler_fn )(struct sc_callback *, void *event_info)
	A callback handler function. More...

Functions
int	sc_callback_alloc (struct sc_callback **cb_out, const struct sc_attr *attr, struct sc_thread *thread)
	Allocate a callback object instance. More...
int	sc_callback_alloc2 (struct sc_callback **cb_out, const struct sc_attr *attr, struct sc_thread *thread, const char *description)
	Allocate a callback object and set description. More...
void	sc_callback_free (struct sc_callback *cb)
	Free a callback object instance. More...
void	sc_callback_set_description (struct sc_callback *cb, const char *fmt,...) __attribute__((format(printf
	Set description of a callback. More...
void static int	sc_callback_is_active (const struct sc_callback *cb)
	Returns true if a callback object is active. More...
static void	sc_callback_remove (struct sc_callback *cb)
	Unregister a callback object from its event source. More...
void	sc_callback_on_idle (struct sc_callback *cb)
	Request a callback when the thread is idle. More...
int	sc_epoll_ctl (struct sc_thread *thread, int op, int fd, unsigned events, struct sc_callback *cb)
	Request a callback when the thread is idle. More...

Detailed Description

sc_callback: Interface for event notification.

Typedef Documentation

typedef void( sc_callback_handler_fn)(struct sc_callback *, void *event_info)

A callback handler function.

Parameters

callback	The callback struct registered with this callback.
event_info	If callback was registered using sc_epoll_ctl this will contain the uint32_t epoll_events bitmask (see man 2 epoll_ctl) In all other cases this is not used.

Function Documentation

int sc_callback_alloc	(	struct sc_callback **	cb_out,
		const struct sc_attr *	attr,
		struct sc_thread *	thread
	)

Allocate a callback object instance.

Parameters

cb_out	The allocated callback object is returned here
attr	Attributes
thread	The thread the callback will be used with

Returns

0 on success, or a negative error code.

This function allocates a callback object instance.

Before using the callback object the sc_callback::cb_handler_fn field must be initialised. The sc_callback::cb_private field may be used to store or point to caller-specific state.

A callback object can only be registered with a single event source at a time. If a callback object is registered with an event source it is "active". If an active callback is registered with an event source, it is automatically removed from the previous event source.

int sc_callback_alloc2	(	struct sc_callback **	cb_out,
		const struct sc_attr *	attr,
		struct sc_thread *	thread,
		const char *	description
	)

Allocate a callback object and set description.

Parameters

cb_out	The allocated callback object is returned here
attr	Attributes
thread	The thread the callback will be used with
description	Description of callback (used for log traces)

Returns

0 on success, or a negative error code.

This function behaves as sc_callback_alloc() except that you can also set a custom description.

void sc_callback_free

(

struct sc_callback *

cb

)

Free a callback object instance.

Parameters

cb	The callback object to free

This function frees a callback object instance.

void static int sc_callback_is_active ( const struct sc_callback *  cb )

inlinestatic

Returns true if a callback object is active.

Parameters

cb	The callback object

void sc_callback_on_idle

(

struct sc_callback *

cb

)

Request a callback when the thread is idle.

Parameters

cb	The callback object

The callback will be invoked from the associated thread's polling loop if there is no work done in that loop iteration. ie. The when thread is idle.

The callback is only invoked once. If further callbacks are wanted the callback must be reregistered explicitly.

static void sc_callback_remove ( struct sc_callback *  cb )

inlinestatic

Unregister a callback object from its event source.

Parameters

cb	The callback object

This function has no effect if the callback object is not active.

void sc_callback_set_description	(	struct sc_callback *	cb,
		const char *	fmt,
			...
	)

Set description of a callback.

Parameters

cb	The callback object
fmt	Printf-style format string

This function sets the description for a callback object. The description is currently only used in log traces.

If fmt is NULL, then log tracing is suppressed for callback cb.

int sc_epoll_ctl	(	struct sc_thread *	thread,
		int	op,
		int	fd,
		unsigned	events,
		struct sc_callback *	cb
	)

Request a callback when the thread is idle.

Parameters

thread	The thread managing fd
op	EPOLL_CTL_ADD, EPOLL_CTL_MOD or EPOLL_CTL_DEL
fd	The file descriptor
events	Event flags (EPOLLIN, EPOLLOUT etc.)
cb	The callback object

Returns

0 on success, or a negative error code.

Request a callback when a file descriptor is readable or writable, or if op is EPOLL_CTL_DEL then cancel a callback.

This function uses epoll as the underlying mechanism to manage file descriptors, so please refer to the documentation of epoll for detailed semantics.

events and cb are ignored when op is EPOLL_CTL_DEL.

A callback registered via this interface cannot be removed with sc_callback_remove, and must not be re-registered with another event source without first calling sc_epoll_ctl with op set to EPOLL_CTL_DEL.