Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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

NAME
       IV_WAIT_INTEREST_INIT, iv_wait_interest_register, iv_wait_interest_reg-
       ister_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  reg-
       isters  a  struct  iv_wait_interest  object  by	calling	iv_wait_inter-
       est_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_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  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_in-
       terest_register_spawn  argument	fn,  with argument cookie as its argu-
       ment.

       Once a process state change occurs  (as	indicated  by  delivery	 of  a
       SIGCHLD	signal	to the current process), iv_wait calls wait4(2)	to re-
       turn 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	avail-
       able 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)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=IV_WAIT_INTEREST_INIT&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help