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)