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)