NAME

       IV_WAIT_INTEREST_INIT,     iv_wait_interest_register,     iv_wait_interest_register_spawn,
       iv_wait_interest_unregister, iv_wait_interest_kill - ivykis wait4(2) wrapper

SYNOPSIS

       #include <iv_wait.h>

       struct iv_wait_interest {
               pid_t           pid;
               void            *cookie;
               void            (*handler)(void *cookie, int status,
                                          struct rusage *rusage);
       };

       void IV_WAIT_INTEREST_INIT(struct iv_wait_interest *this);
       int iv_wait_interest_register(struct iv_wait_interest *this);
       int iv_wait_interest_register_spawn(struct iv_wait_interest  *this,  void  (*fn)(void  *),
       void *cookie);
       void iv_wait_interest_unregister(struct iv_wait_interest *this);
       int iv_wait_interest_kill(struct iv_wait_interest *this, int sig);

DESCRIPTION

       iv_wait  is  an  ivykis(3)  wrapper  around  wait4(2),  integrating  process  state change
       notification with the ivykis event loop.

       An ivykis application desiring process  state  change  notifications  registers  a  struct
       iv_wait_interest  object by calling iv_wait_interest_register, after having initialised it
       with IV_WAIT_INTEREST_INIT and subsequently having  filled  in  the  ->pid,  ->cookie  and
       ->handler members.

       Alternatively, an ivykis application can use iv_wait_interest_register_spawn to atomically
       fork off a child process and register a struct iv_wait_interest for it.  In this  context,
       'atomically'  means  that  the  call to iv_wait_interest_register_spawn will be serialised
       with respect to invocations of wait4(2), which closes the race where process state  change
       notifications  can  occur  and  be  delivered  between  forking  off the child process and
       registering a struct iv_wait_interest for the child's pid.  The child process will run the
       function given by the iv_wait_interest_register_spawn argument fn, with argument cookie as
       its argument.

       Once a process state change occurs (as indicated by delivery of a SIGCHLD  signal  to  the
       current  process),  iv_wait  calls  wait4(2) to return information about the process state
       change, looks up the returned process ID in the set of registered struct  iv_wait_interest
       objects,  and  if there is a registered interest with a matching ->pid field, arranges for
       that object's callback function to be called in the thread that the object was  registered
       in.

       Process  state change notifications will continue to be delivered to the object's callback
       function until iv_wait_interest_unregister is called on the object or until a WIFEXITED or
       WIFSIGNALED status for this pid is returned by wait4(2).

       Delivery  of  a  WIFEXITED  or  WIFSIGNALED  status  does not automatically unregister the
       object, this always needs to be done explicitly.

       Unregistering a struct iv_wait_interest object can only be done from the thread that  that
       object  was  registered  in,  but  within  that  thread,  can safely be done from (and its
       underlying memory allocation can safely be freed from) its own callback function.

       Registering multiple struct iv_wait_interest objects for the same process ID will  produce
       undefined behavior.

       To  send  a  signal  to  a  child  process, use iv_wait_interest_kill.  This function will
       internally serialise with invocations of wait4(2), to avoid the  race  between  sending  a
       signal  to  a  process  and  collecting a termination notification for that process (which
       makes its pid available for reuse).

       Internally, iv_wait is implemented using iv_signal(3) and iv_event(3).

SEE ALSO

       ivykis(3), iv_signal(3), iv_event(3), wait4(2)