Debian Codegraph @

upstream/debian-unstable/man3/sd_event_wait.3

raw
1 '\" t
2 .TH "SD_EVENT_WAIT" "3" "" "systemd 261~rc3" "sd_event_wait"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd_event_wait, sd_event_prepare, sd_event_dispatch, sd_event_get_state, sd_event_get_iteration, SD_EVENT_INITIAL, SD_EVENT_PREPARING, SD_EVENT_ARMED, SD_EVENT_PENDING, SD_EVENT_RUNNING, SD_EVENT_EXITING, SD_EVENT_FINISHED \- Low\-level event loop operations
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-event\&.h>
29 .fi
30 .ft
31 .sp
32 .ft B
33 .nf
34 enum {
35 \fBSD_EVENT_INITIAL\fR,
36 \fBSD_EVENT_PREPARING\fR,
37 \fBSD_EVENT_ARMED\fR,
38 \fBSD_EVENT_PENDING\fR,
39 \fBSD_EVENT_RUNNING\fR,
40 \fBSD_EVENT_EXITING\fR,
41 \fBSD_EVENT_FINISHED\fR,
42 };
43 .fi
44 .ft
45 .HP \w'int\ sd_event_prepare('u
46 .BI "int sd_event_prepare(sd_event\ *" "event" ");"
47 .HP \w'int\ sd_event_wait('u
48 .BI "int sd_event_wait(sd_event\ *" "event" ", uint64_t\ " "usec" ");"
49 .HP \w'int\ sd_event_dispatch('u
50 .BI "int sd_event_dispatch(sd_event\ *" "event" ");"
51 .HP \w'int\ sd_event_get_state('u
52 .BI "int sd_event_get_state(sd_event\ *" "event" ");"
53 .HP \w'int\ sd_event_get_iteration('u
54 .BI "int sd_event_get_iteration(sd_event\ *" "event" ", uint64_t\ *" "ret" ");"
55 .SH "DESCRIPTION"
56 .PP
57 The low\-level
58 \fBsd_event_prepare()\fR,
59 \fBsd_event_wait()\fR
60 and
61 \fBsd_event_dispatch()\fR
62 functions may be used to execute specific phases of an event loop\&. See
63 \fBsd_event_run\fR(3)
64 and
65 \fBsd_event_loop\fR(3)
66 for higher\-level functions that execute individual but complete iterations of an event loop or run it continuously\&.
67 .PP
68 \fBsd_event_prepare()\fR
69 checks for pending events and arms necessary timers\&. If any events are ready to be processed ("pending"), it returns a positive, non\-zero value, and the caller should process these events with
70 \fBsd_event_dispatch()\fR\&.
71 .PP
72 \fBsd_event_dispatch()\fR
73 dispatches the highest priority event source that has a pending event\&. On success,
74 \fBsd_event_dispatch()\fR
75 returns either zero, which indicates that no further event sources may be dispatched and exiting of the event loop was requested via
76 \fBsd_event_exit\fR(3); or a positive non\-zero value, which means that an event source was dispatched and the loop returned to its initial state, and the caller should initiate the next event loop iteration by invoking
77 \fBsd_event_prepare()\fR
78 again\&.
79 .PP
80 In case
81 \fBsd_event_prepare()\fR
82 returned zero,
83 \fBsd_event_wait()\fR
84 should be called to wait for further events or a timeout\&. If any events are ready to be processed, it returns a positive, non\-zero value, and the events should be dispatched with
85 \fBsd_event_dispatch()\fR\&. Otherwise, the event loop returned to its initial state and the next event loop iteration should be initiated by invoking
86 \fBsd_event_prepare()\fR
87 again\&.
88 .PP
89 \fBsd_event_get_state()\fR
90 may be used to determine the state the event loop is currently in\&. It returns one of the states described below\&.
91 .PP
92 \fBsd_event_get_iteration()\fR
93 may be used to determine the current iteration of the event loop\&. It returns an unsigned 64\-bit integer containing a counter that increases monotonically with each iteration of the event loop, starting with 0\&. The counter is increased at the time of the
94 \fBsd_event_prepare()\fR
95 invocation\&.
96 .PP
97 All five functions take, as the first argument, the event loop object
98 \fIevent\fR
99 that has been created with
100 \fBsd_event_new()\fR\&. The timeout for
101 \fBsd_event_wait()\fR
102 is specified in
103 \fIusec\fR
104 in microseconds\&.
105 \fB(uint64_t) \-1\fR
106 may be used to specify an infinite timeout\&.
107 .SH "STATE MACHINE"
108 .PP
109 The event loop knows the following states, that may be queried with
110 \fBsd_event_get_state()\fR\&.
111 .PP
112 \fBSD_EVENT_INITIAL\fR
113 .RS 4
114 The initial state the event loop is in, before each event loop iteration\&. Use
115 \fBsd_event_prepare()\fR
116 to transition the event loop into the
117 \fBSD_EVENT_ARMED\fR
118 or
119 \fBSD_EVENT_PENDING\fR
120 states\&.
121 .sp
122 Added in version 229\&.
123 .RE
124 .PP
125 \fBSD_EVENT_PREPARING\fR
126 .RS 4
127 An event source is currently being prepared, i\&.e\&. the preparation handler is currently being executed, as set with
128 \fBsd_event_source_set_prepare\fR(3)\&. This state is only seen in the event source preparation handler that is invoked from the
129 \fBsd_event_prepare()\fR
130 call and is immediately followed by
131 \fBSD_EVENT_ARMED\fR
132 or
133 \fBSD_EVENT_PENDING\fR\&.
134 .sp
135 Added in version 229\&.
136 .RE
137 .PP
138 \fBSD_EVENT_ARMED\fR
139 .RS 4
140 \fBsd_event_prepare()\fR
141 has been called and no event sources were ready to be dispatched\&. Use
142 \fBsd_event_wait()\fR
143 to wait for new events, and transition into
144 \fBSD_EVENT_PENDING\fR
145 or back into
146 \fBSD_EVENT_INITIAL\fR\&.
147 .sp
148 Added in version 229\&.
149 .RE
150 .PP
151 \fBSD_EVENT_PENDING\fR
152 .RS 4
153 \fBsd_event_prepare()\fR
154 or
155 \fBsd_event_wait()\fR
156 have been called and there were event sources with events pending\&. Use
157 \fBsd_event_dispatch()\fR
158 to dispatch the highest priority event source and transition back to
159 \fBSD_EVENT_INITIAL\fR, or
160 \fBSD_EVENT_FINISHED\fR\&.
161 .sp
162 Added in version 229\&.
163 .RE
164 .PP
165 \fBSD_EVENT_RUNNING\fR
166 .RS 4
167 A regular event source is currently being dispatched\&. This state is only seen in the event source handler that is invoked from the
168 \fBsd_event_dispatch()\fR
169 call, and is immediately followed by
170 \fBSD_EVENT_INITIAL\fR
171 or
172 \fBSD_EVENT_FINISHED\fR
173 as soon the event source handler returns\&. Note that during dispatching of exit event sources the
174 \fBSD_EVENT_EXITING\fR
175 state is seen instead\&.
176 .sp
177 Added in version 229\&.
178 .RE
179 .PP
180 \fBSD_EVENT_EXITING\fR
181 .RS 4
182 Similar to
183 \fBSD_EVENT_RUNNING\fR
184 but is the state in effect while dispatching exit event sources\&. It is followed by
185 \fBSD_EVENT_INITIAL\fR
186 or
187 \fBSD_EVENT_FINISHED\fR
188 as soon as the event handler returns\&.
189 .sp
190 Added in version 229\&.
191 .RE
192 .PP
193 \fBSD_EVENT_FINISHED\fR
194 .RS 4
195 The event loop has exited\&. All exit event sources have run\&. If the event loop is in this state it serves no purpose anymore, and should be freed\&.
196 .sp
197 Added in version 229\&.
198 .RE
199 .PP
200 A simplified flow chart of the states and the calls to transition between them is shown below\&. Note that
201 \fBSD_EVENT_PREPARING\fR,
202 \fBSD_EVENT_RUNNING\fR
203 and
204 \fBSD_EVENT_EXITING\fR
205 are not shown here\&.
206 .sp
207 .if n \{\
208 .RS 4
209 .\}
210 .nf
211 INITIAL \-<\-\-\-<\-\-\-<\-\-\-<\-\-\-<\-\-\-<\-\-\-<\-\-\-<\-\-\-<\-\-\-<\-\-\-<\-\-\-<\-\-\-\e
212 | |
213 | ^
214 | |
215 v ret == 0 |
216 sd_event_prepare() >\-\-\->\-\-\->\-\-\->\-\-\->\- ARMED |
217 | | ^
218 | ret > 0 | |
219 | | |
220 v v ret == 0 |
221 PENDING <\-\-\-<\-\-\-<\-\-\-<\-\-\-<\-\-\-< sd_event_wait() >\-\-\->\-\-\->\-\-+
222 | ret > 0 ^
223 | |
224 | |
225 v |
226 sd_event_dispatch() >\-\-\->\-\-\->\-\-\->\-\-\->\-\-\->\-\-\->\-\-\->\-\-\->\-\-\->\-\-\->/
227 | ret > 0
228 | ret == 0
229 |
230 v
231 FINISHED
232 .fi
233 .if n \{\
234 .RE
235 .\}
236 .SH "RETURN VALUE"
237 .PP
238 On success, these functions return 0 or a positive integer\&. On failure, they return a negative errno\-style error code\&. In case of
239 \fBsd_event_prepare()\fR
240 and
241 \fBsd_event_wait()\fR, a positive, non\-zero return code indicates that events are ready to be processed and zero indicates that no events are ready\&. In case of
242 \fBsd_event_dispatch()\fR, a positive, non\-zero return code indicates that the event loop returned to its initial state and zero indicates the event loop has exited\&.
243 \fBsd_event_get_state()\fR
244 returns a positive or zero state on success\&.
245 .SS "Errors"
246 .PP
247 Returned errors may indicate the following problems:
248 .PP
249 \fB\-EINVAL\fR
250 .RS 4
251 The
252 \fIevent\fR
253 parameter is invalid or
254 \fBNULL\fR\&.
255 .RE
256 .PP
257 \fB\-EBUSY\fR
258 .RS 4
259 The event loop object is not in the right state\&.
260 .RE
261 .PP
262 \fB\-ESTALE\fR
263 .RS 4
264 The event loop is already terminated\&.
265 .RE
266 .PP
267 \fB\-ECHILD\fR
268 .RS 4
269 The event loop has been created in a different process, library or module instance\&.
270 .RE
271 .PP
272 Other errors are possible, too\&.
273 .SH "NOTES"
274 .PP
275 Functions described here are available as a shared library, which can be compiled against and linked to with the
276 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
277 file\&.
278 .PP
279 The code described here uses
280 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
281 \fBsetenv\fR(3)
282 from a parallel thread\&. It is recommended to only do calls to
283 \fBsetenv()\fR
284 from an early phase of the program when no other threads have been started\&.
285 .SH "HISTORY"
286 .PP
287 \fBsd_event_prepare()\fR,
288 \fBsd_event_wait()\fR,
289 \fBsd_event_dispatch()\fR, and
290 \fBsd_event_get_state()\fR
291 were added in version 221\&.
292 .PP
293 \fBsd_event_get_iteration()\fR
294 was added in version 231\&.
295 .SH "SEE ALSO"
296 .PP
297 \fBsystemd\fR(1), \fBsd_event_new\fR(3), \fBsd_event_add_io\fR(3), \fBsd_event_add_time\fR(3), \fBsd_event_add_signal\fR(3), \fBsd_event_add_child\fR(3), \fBsd_event_add_inotify\fR(3), \fBsd_event_add_defer\fR(3), \fBsd_event_run\fR(3), \fBsd_event_get_fd\fR(3), \fBsd_event_source_set_prepare\fR(3)