SolarCapture C Bindings User Guide  SF-115721-CD
Draft 2A
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
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
callbackThe callback struct registered with this callback.
event_infoIf 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_outThe allocated callback object is returned here
attrAttributes
threadThe 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_outThe allocated callback object is returned here
attrAttributes
threadThe thread the callback will be used with
descriptionDescription 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
cbThe 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
cbThe callback object
void sc_callback_on_idle ( struct sc_callback cb)

Request a callback when the thread is idle.

Parameters
cbThe 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
cbThe 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
cbThe callback object
fmtPrintf-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
threadThe thread managing fd
opEPOLL_CTL_ADD, EPOLL_CTL_MOD or EPOLL_CTL_DEL
fdThe file descriptor
eventsEvent flags (EPOLLIN, EPOLLOUT etc.)
cbThe 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.