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, ar-
       ranges 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)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO

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

home | help