DragonFly On-Line Manual Pages

iv_event_raw(3)           ivykis programmer's manual           iv_event_raw(3)

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)

ivykis                            2010-09-02                   iv_event_raw(3)