2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
6 <refentry id=
"sd_event_wait" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
9 <title>sd_event_wait
</title>
10 <productname>systemd
</productname>
14 <refentrytitle>sd_event_wait
</refentrytitle>
15 <manvolnum>3</manvolnum>
19 <refname>sd_event_wait
</refname>
20 <refname>sd_event_prepare
</refname>
21 <refname>sd_event_dispatch
</refname>
22 <refname>sd_event_get_state
</refname>
23 <refname>sd_event_get_iteration
</refname>
24 <refname>SD_EVENT_INITIAL
</refname>
25 <refname>SD_EVENT_PREPARING
</refname>
26 <refname>SD_EVENT_ARMED
</refname>
27 <refname>SD_EVENT_PENDING
</refname>
28 <refname>SD_EVENT_RUNNING
</refname>
29 <refname>SD_EVENT_EXITING
</refname>
30 <refname>SD_EVENT_FINISHED
</refname>
32 <refpurpose>Low-level event loop operations
</refpurpose>
37 <funcsynopsisinfo>#include
<systemd/sd-event.h
></funcsynopsisinfo>
39 <funcsynopsisinfo><token>enum
</token> {
40 <constant>SD_EVENT_INITIAL
</constant>,
41 <constant>SD_EVENT_PREPARING
</constant>,
42 <constant>SD_EVENT_ARMED
</constant>,
43 <constant>SD_EVENT_PENDING
</constant>,
44 <constant>SD_EVENT_RUNNING
</constant>,
45 <constant>SD_EVENT_EXITING
</constant>,
46 <constant>SD_EVENT_FINISHED
</constant>,
50 <funcdef>int
<function>sd_event_prepare
</function></funcdef>
51 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
55 <funcdef>int
<function>sd_event_wait
</function></funcdef>
56 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
57 <paramdef>uint64_t
<parameter>usec
</parameter></paramdef>
61 <funcdef>int
<function>sd_event_dispatch
</function></funcdef>
62 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
66 <funcdef>int
<function>sd_event_get_state
</function></funcdef>
67 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
71 <funcdef>int
<function>sd_event_get_iteration
</function></funcdef>
72 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
73 <paramdef>uint64_t *
<parameter>ret
</parameter></paramdef>
80 <title>Description
</title>
82 <para>The low-level
<function>sd_event_prepare()
</function>,
83 <function>sd_event_wait()
</function> and
84 <function>sd_event_dispatch()
</function> functions may be used to
85 execute specific phases of an event loop. See
86 <citerefentry><refentrytitle>sd_event_run
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
88 <citerefentry><refentrytitle>sd_event_loop
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
89 for higher-level functions that execute individual but complete
90 iterations of an event loop or run it continuously.
</para>
92 <para><function>sd_event_prepare()
</function> checks for pending
93 events and arms necessary timers. If any events are ready to be
94 processed (
"pending"), it returns a positive, non-zero value, and the caller
95 should process these events with
96 <function>sd_event_dispatch()
</function>.
</para>
98 <para><function>sd_event_dispatch()
</function> dispatches the
99 highest priority event source that has a pending event. On
100 success,
<function>sd_event_dispatch()
</function> returns either
101 zero, which indicates that no further event sources may be
102 dispatched and exiting of the event loop was requested via
103 <citerefentry><refentrytitle>sd_event_exit
</refentrytitle><manvolnum>3</manvolnum></citerefentry>;
104 or a positive non-zero value, which means that an event source was
105 dispatched and the loop returned to its initial state, and the
106 caller should initiate the next event loop iteration by invoking
107 <function>sd_event_prepare()
</function> again.
</para>
109 <para>In case
<function>sd_event_prepare()
</function> returned
110 zero,
<function>sd_event_wait()
</function> should be called to
111 wait for further events or a timeout. If any events are ready to
112 be processed, it returns a positive, non-zero value, and the
113 events should be dispatched with
114 <function>sd_event_dispatch()
</function>. Otherwise, the event
115 loop returned to its initial state and the next event loop
116 iteration should be initiated by invoking
117 <function>sd_event_prepare()
</function> again.
</para>
119 <para><function>sd_event_get_state()
</function> may be used to
120 determine the state the event loop is currently in. It returns one
121 of the states described below.
</para>
123 <para><function>sd_event_get_iteration()
</function> may be used to determine the current iteration of the event
124 loop. It returns an unsigned
64-bit integer containing a counter that increases monotonically with each iteration of
125 the event loop, starting with
0. The counter is increased at the time of the
126 <function>sd_event_prepare()
</function> invocation.
</para>
128 <para>All five functions take, as the first argument, the event loop object
<parameter>event
</parameter> that has
129 been created with
<function>sd_event_new()
</function>. The timeout for
<function>sd_event_wait()
</function> is
130 specified in
<parameter>usec
</parameter> in microseconds.
<constant>(uint64_t) -
1</constant> may be used to
131 specify an infinite timeout.
</para>
135 <title>State Machine
</title>
137 <para>The event loop knows the following states, that may be
138 queried with
<function>sd_event_get_state()
</function>.
</para>
142 <term><constant>SD_EVENT_INITIAL
</constant></term>
144 <listitem><para>The initial state the event loop is in,
145 before each event loop iteration. Use
146 <function>sd_event_prepare()
</function> to transition the
147 event loop into the
<constant>SD_EVENT_ARMED
</constant> or
148 <constant>SD_EVENT_PENDING
</constant> states.
</para>
150 <xi:include href=
"version-info.xml" xpointer=
"v229"/></listitem>
154 <term><constant>SD_EVENT_PREPARING
</constant></term>
156 <listitem><para>An event source is currently being prepared,
157 i.e. the preparation handler is currently being executed, as
159 <citerefentry><refentrytitle>sd_event_source_set_prepare
</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This
160 state is only seen in the event source preparation handler
161 that is invoked from the
162 <function>sd_event_prepare()
</function> call and is
163 immediately followed by
<constant>SD_EVENT_ARMED
</constant> or
164 <constant>SD_EVENT_PENDING
</constant>.
</para>
166 <xi:include href=
"version-info.xml" xpointer=
"v229"/></listitem>
170 <term><constant>SD_EVENT_ARMED
</constant></term>
172 <listitem><para><function>sd_event_prepare()
</function> has
173 been called and no event sources were ready to be
174 dispatched. Use
<function>sd_event_wait()
</function> to wait
175 for new events, and transition into
176 <constant>SD_EVENT_PENDING
</constant> or back into
177 <constant>SD_EVENT_INITIAL
</constant>.
</para>
179 <xi:include href=
"version-info.xml" xpointer=
"v229"/></listitem>
183 <term><constant>SD_EVENT_PENDING
</constant></term>
185 <listitem><para><function>sd_event_prepare()
</function> or
186 <function>sd_event_wait()
</function> have been called and
187 there were event sources with events pending. Use
188 <function>sd_event_dispatch()
</function> to dispatch the
189 highest priority event source and transition back to
190 <constant>SD_EVENT_INITIAL
</constant>, or
191 <constant>SD_EVENT_FINISHED
</constant>.
</para>
193 <xi:include href=
"version-info.xml" xpointer=
"v229"/></listitem>
197 <term><constant>SD_EVENT_RUNNING
</constant></term>
199 <listitem><para>A regular event source is currently being
200 dispatched. This state is only seen in the event source
201 handler that is invoked from the
202 <function>sd_event_dispatch()
</function> call, and is
203 immediately followed by
<constant>SD_EVENT_INITIAL
</constant>
204 or
<constant>SD_EVENT_FINISHED
</constant> as soon the event
205 source handler returns. Note that during dispatching of exit
206 event sources the
<constant>SD_EVENT_EXITING
</constant> state
207 is seen instead.
</para>
209 <xi:include href=
"version-info.xml" xpointer=
"v229"/></listitem>
213 <term><constant>SD_EVENT_EXITING
</constant></term>
215 <listitem><para>Similar to
216 <constant>SD_EVENT_RUNNING
</constant> but is the state in
217 effect while dispatching exit event sources. It is followed by
218 <constant>SD_EVENT_INITIAL
</constant> or
219 <constant>SD_EVENT_FINISHED
</constant> as soon as the event
220 handler returns.
</para>
222 <xi:include href=
"version-info.xml" xpointer=
"v229"/></listitem>
226 <term><constant>SD_EVENT_FINISHED
</constant></term>
228 <listitem><para>The event loop has exited. All exit event
229 sources have run. If the event loop is in this state it serves
230 no purpose anymore, and should be freed.
</para>
232 <xi:include href=
"version-info.xml" xpointer=
"v229"/></listitem>
237 <para>A simplified flow chart of the states and the calls to
238 transition between them is shown below. Note that
239 <constant>SD_EVENT_PREPARING
</constant>,
240 <constant>SD_EVENT_RUNNING
</constant> and
241 <constant>SD_EVENT_EXITING
</constant> are not shown here.
</para>
244 INITIAL -
<---
<---
<---
<---
<---
<---
<---
<---
<---
<---
<---
<---\
249 sd_event_prepare()
>---
>---
>---
>---
>- ARMED |
254 PENDING
<---
<---
<---
<---
<---
< sd_event_wait()
>---
>---
>--+
259 sd_event_dispatch()
>---
>---
>---
>---
>---
>---
>---
>---
>---
>---
>/
269 <title>Return Value
</title>
271 <para>On success, these functions return
0 or a positive integer. On failure, they return a negative
272 errno-style error code. In case of
<function>sd_event_prepare()
</function> and
273 <function>sd_event_wait()
</function>, a positive, non-zero return code indicates that events are ready to
274 be processed and zero indicates that no events are ready. In case of
275 <function>sd_event_dispatch()
</function>, a positive, non-zero return code indicates that the event loop
276 returned to its initial state and zero indicates the event loop has
277 exited.
<function>sd_event_get_state()
</function> returns a positive or zero state on success.
</para>
280 <title>Errors
</title>
282 <para>Returned errors may indicate the following problems:
</para>
286 <term><constant>-EINVAL
</constant></term>
288 <listitem><para>The
<parameter>event
</parameter> parameter is invalid or
<constant>NULL
</constant>.
293 <term><constant>-EBUSY
</constant></term>
295 <listitem><para>The event loop object is not in the right state.
</para></listitem>
299 <term><constant>-ESTALE
</constant></term>
301 <listitem><para>The event loop is already terminated.
</para></listitem>
306 <term><constant>-ECHILD
</constant></term>
308 <listitem><para>The event loop has been created in a different process, library or module instance.
</para></listitem>
314 <para>Other errors are possible, too.
</para>
318 <xi:include href=
"libsystemd-pkgconfig.xml" />
321 <title>History
</title>
322 <para><function>sd_event_prepare()
</function>,
323 <function>sd_event_wait()
</function>,
324 <function>sd_event_dispatch()
</function>, and
325 <function>sd_event_get_state()
</function> were added in version
221.
</para>
326 <para><function>sd_event_get_iteration()
</function> was added in version
231.
</para>
330 <title>See Also
</title>
332 <para><simplelist type=
"inline">
333 <member><citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
334 <member><citerefentry><refentrytitle>sd_event_new
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
335 <member><citerefentry><refentrytitle>sd_event_add_io
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
336 <member><citerefentry><refentrytitle>sd_event_add_time
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
337 <member><citerefentry><refentrytitle>sd_event_add_signal
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
338 <member><citerefentry><refentrytitle>sd_event_add_child
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
339 <member><citerefentry><refentrytitle>sd_event_add_inotify
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
340 <member><citerefentry><refentrytitle>sd_event_add_defer
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
341 <member><citerefentry><refentrytitle>sd_event_run
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
342 <member><citerefentry><refentrytitle>sd_event_get_fd
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
343 <member><citerefentry><refentrytitle>sd_event_source_set_prepare
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>