NAME¶
IV_EVENT_RAW_INIT, iv_event_raw_register, iv_event_raw_unregister,
iv_event_raw_post - manage ivykis objects for event notification
SYNOPSIS¶
#include <iv_event_raw.h>
struct iv_event_raw {
void *cookie;
void (*handler)(void *);
};
void IV_EVENT_RAW_INIT(struct iv_event_raw *this);
int iv_event_raw_register(struct iv_event_raw *this);
void iv_event_raw_unregister(struct iv_event_raw *this);
void iv_event_raw_post(struct iv_event_raw *this);
DESCRIPTION¶
iv_event_raw provides a way for delivering events to
ivykis(3)
recipients across thread and process boundaries.
The intended event recipient calls
IV_EVENT_RAW_INIT on a
struct
iv_event_raw object, fills in
->cookie and
->handler,
and then calls
iv_event_raw_register on the object.
To generate an event, call
iv_event_raw_post on the previously
initialized
struct iv_event_raw object. This will cause the callback
specified by
->handler to be called in the thread that the
struct
iv_event_raw object was registered in, with
->cookie as its sole
argument.
To deinitialize a
struct iv_event_raw object, call
iv_event_raw_unregister from the same thread that
iv_event_raw_register was called from on that object.
It is permitted to unregister a
struct iv_event_raw object from any
ivykis callback function in the thread it was registered in, including from a
callback function triggered by this object, and it is permitted to free the
memory corresponding to an unregistered object from its own callback function.
iv_event_raw_post can be called from the same thread that
iv_event_raw_register was called from, from a different thread in the
same process, or even from a different process, and can safely be called from
signal handlers.
If posting an event only ever needs to be done from within the same process, see
iv_event(3) for a lighter-weight alternative to
iv_event_raw.
Internally,
iv_event_raw is implemented by registering a file descriptor
(a struct
iv_fd(3)) with the recipient thread's ivykis event loop, and
by causing that file descriptor to become readable upon a call to
iv_event_raw_post.
If
eventfd(2) is available, it will be used to procure the abovementioned
file descriptor. If not,
iv_event_raw will fall back to
pipe(2)
as the source of its file descriptors.
eventfd(2) is preferred as it
requires only one file descriptor table entry (while
pipe(2) requires
two), and has much less kernel overhead than
pipe(2) has.
SEE ALSO¶
ivykis(3),
iv_event(3),
eventfd(2),
pipe(2)