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(const 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)