1iv_wait(3) ivykis programmer's manual iv_wait(3)
2
6 IV_WAIT_INTEREST_INIT, iv_wait_interest_register, iv_wait_interest_reg‐
7 ister_spawn, iv_wait_interest_unregister, iv_wait_interest_kill -
8 ivykis wait4(2) wrapper
9
11 #include <iv_wait.h>
12 struct iv_wait_interest {
14 pid_t pid;
15 void *cookie;
16 void (*handler)(void *cookie, int status,
17 const struct rusage *rusage);
18 };
19 void IV_WAIT_INTEREST_INIT(struct iv_wait_interest *this);
21 int iv_wait_interest_register(struct iv_wait_interest *this);
22 int iv_wait_interest_register_spawn(struct iv_wait_interest *this, void
23 (*fn)(void *), void *cookie);
24 void iv_wait_interest_unregister(struct iv_wait_interest *this);
25 int iv_wait_interest_kill(const struct iv_wait_interest *this, int
26 sig);
27
29 iv_wait is an ivykis(3) wrapper around wait4(2), integrating process
30 state change notification with the ivykis event loop.
31 An ivykis application desiring process state change notifications reg‐
33 isters a struct iv_wait_interest object by calling iv_wait_inter‐
34 est_register, after having initialised it with IV_WAIT_INTEREST_INIT
35 and subsequently having filled in the ->pid, ->cookie and ->handler
36 members.
37 Alternatively, an ivykis application can use iv_wait_interest_regis‐
39 ter_spawn to atomically fork off a child process and register a struct
40 iv_wait_interest for it. In this context, 'atomically' means that the
41 call to iv_wait_interest_register_spawn will be serialised with respect
42 to invocations of wait4(2), which closes the race where process state
43 change notifications can occur and be delivered between forking off the
44 child process and registering a struct iv_wait_interest for the child's
45 pid. The child process will run the function given by the
46 iv_wait_interest_register_spawn argument fn, with argument cookie as
47 its argument.
48 Once a process state change occurs (as indicated by delivery of a
50 SIGCHLD signal to the current process), iv_wait calls wait4(2) to
51 return information about the process state change, looks up the
52 returned process ID in the set of registered struct iv_wait_interest
53 objects, and if there is a registered interest with a matching ->pid
54 field, arranges for that object's callback function to be called in the
55 thread that the object was registered in.
56 Process state change notifications will continue to be delivered to the
58 object's callback function until iv_wait_interest_unregister is called
59 on the object or until a WIFEXITED or WIFSIGNALED status for this pid
60 is returned by wait4(2).
61 Delivery of a WIFEXITED or WIFSIGNALED status does not automatically
63 unregister the object, this always needs to be done explicitly.
64 Unregistering a struct iv_wait_interest object can only be done from
66 the thread that that object was registered in, but within that thread,
67 can safely be done from (and its underlying memory allocation can
68 safely be freed from) its own callback function.
69 Registering multiple struct iv_wait_interest objects for the same
71 process ID will produce undefined behavior.
72 To send a signal to a child process, use iv_wait_interest_kill. This
74 function will internally serialise with invocations of wait4(2), to
75 avoid the race between sending a signal to a process and collecting a
76 termination notification for that process (which makes its pid avail‐
77 able for reuse).
78 Internally, iv_wait is implemented using iv_signal(3) and iv_event(3).
80
82 ivykis(3), iv_signal(3), iv_event(3), wait4(2)
83ivykis 2010-09-03 iv_wait(3)