home | help 
iv_wait(3)		   ivykis programmer's manual		      iv_wait(3)

NAME
     IV_WAIT_INTEREST_INIT,  iv_wait_interest_register,  iv_wait_interest_regis-
     ter_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, af-
     ter having initialised it with IV_WAIT_INTEREST_INIT and subsequently  hav-
     ing filled in the ->pid, ->cookie and ->handler members.

     Alternatively,   an  ivykis  application  can  use  iv_wait_interest_regis-
     ter_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 invo-
     cations of wait4(2), which closes the race where process state change noti-
     fications	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 informa-
     tion 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 ob-
     ject'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 unreg-
     ister 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 func-
     tion  will  internally serialise with invocations of wait4(2), to avoid the
     race between sending a signal to a process and collecting a termination no-
     tification 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)

ivykis				   2010-09-03			      iv_wait(3)
home | help