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