![]() |
SolarCapture C Bindings User Guide
SF-115721-CD
Draft 2A
|
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... | |
sc_callback: Interface for event notification.
typedef void( sc_callback_handler_fn)(struct sc_callback *, void *event_info) |
A callback handler function.
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. |
int sc_callback_alloc | ( | struct sc_callback ** | cb_out, |
const struct sc_attr * | attr, | ||
struct sc_thread * | thread | ||
) |
Allocate a callback object instance.
cb_out | The allocated callback object is returned here |
attr | Attributes |
thread | The thread the callback will be used with |
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.
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) |
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.
cb | The callback object to free |
This function frees a callback object instance.
|
inlinestatic |
Returns true if a callback object is active.
cb | The callback object |
void sc_callback_on_idle | ( | struct sc_callback * | cb | ) |
Request a callback when the thread is idle.
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.
|
inlinestatic |
Unregister a callback object from its event source.
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.
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.
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 |
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.