IV_EVENT_RAW_INIT(3)

1iv_event_raw(3)           ivykis programmer's manual           iv_event_raw(3)
2
3
4

NAME

6       IV_EVENT_RAW_INIT,    iv_event_raw_register,   iv_event_raw_unregister,
7       iv_event_raw_post - manage ivykis objects for event notification
8

SYNOPSIS

10       #include <iv_event_raw.h>
11
12       struct iv_event_raw {
13               void            *cookie;
14               void            (*handler)(void *);
15       };
16
17       void IV_EVENT_RAW_INIT(struct iv_event_raw *this);
18       int iv_event_raw_register(struct iv_event_raw *this);
19       void iv_event_raw_unregister(struct iv_event_raw *this);
20       void iv_event_raw_post(const struct iv_event_raw *this);
21

DESCRIPTION

23       iv_event_raw provides a way for delivering events to ivykis(3)  recipi‐
24       ents across thread and process boundaries.
25
26       The  intended  event  recipient  calls  IV_EVENT_RAW_INIT  on  a struct
27       iv_event_raw object, fills in ->cookie and ->handler,  and  then  calls
28       iv_event_raw_register on the object.
29
30       To generate an event, call iv_event_raw_post on the previously initial‐
31       ized struct iv_event_raw object.  This will cause the  callback  speci‐
32       fied  by  ->handler  to  be  called  in  the  thread  that  the  struct
33       iv_event_raw object was registered in, with ->cookie as its sole  argu‐
34       ment.
35
36       To  deinitialize a struct iv_event_raw object, call iv_event_raw_unreg‐
37       ister from the same thread that iv_event_raw_register was  called  from
38       on that object.
39
40       It  is  permitted  to  unregister a struct iv_event_raw object from any
41       ivykis callback function in the thread it was registered in,  including
42       from  a callback function triggered by this object, and it is permitted
43       to free the memory corresponding to an unregistered object from its own
44       callback function.
45
46       iv_event_raw_post   can   be   called   from   the   same  thread  that
47       iv_event_raw_register was called from, from a different thread  in  the
48       same  process,  or  even  from  a  different process, and can safely be
49       called from signal handlers.
50
51       If posting an event only ever needs to be done  from  within  the  same
52       process,   see   iv_event(3)   for   a  lighter-weight  alternative  to
53       iv_event_raw.
54
55       Internally, iv_event_raw is implemented by registering a file  descrip‐
56       tor  (a struct iv_fd(3)) with the recipient thread's ivykis event loop,
57       and by causing that file descriptor to become readable upon a  call  to
58       iv_event_raw_post.
59
60       If  eventfd(2)  is  available, it will be used to procure the abovemen‐
61       tioned file descriptor.  If not, iv_event_raw will fall back to pipe(2)
62       as  the  source of its file descriptors.  eventfd(2) is preferred as it
63       requires only one file descriptor table entry (while  pipe(2)  requires
64       two), and has much less kernel overhead than pipe(2) has.
65

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO