1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
8 Copyright © 2015 Zbigniew Jędrzejewski-Szmek
11 <refentry id="sd_event_wait" xmlns:xi="http://www.w3.org/2001/XInclude">
14 <title>sd_event_wait</title>
15 <productname>systemd</productname>
19 <refentrytitle>sd_event_wait</refentrytitle>
20 <manvolnum>3</manvolnum>
24 <refname>sd_event_wait</refname>
25 <refname>sd_event_prepare</refname>
26 <refname>sd_event_dispatch</refname>
27 <refname>sd_event_get_state</refname>
28 <refname>sd_event_get_iteration</refname>
29 <refname>SD_EVENT_INITIAL</refname>
30 <refname>SD_EVENT_PREPARING</refname>
31 <refname>SD_EVENT_ARMED</refname>
32 <refname>SD_EVENT_PENDING</refname>
33 <refname>SD_EVENT_RUNNING</refname>
34 <refname>SD_EVENT_EXITING</refname>
35 <refname>SD_EVENT_FINISHED</refname>
37 <refpurpose>Low-level event loop operations</refpurpose>
42 <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo>
44 <funcsynopsisinfo><token>enum</token> {
45 <constant>SD_EVENT_INITIAL</constant>,
46 <constant>SD_EVENT_PREPARING</constant>,
47 <constant>SD_EVENT_ARMED</constant>,
48 <constant>SD_EVENT_PENDING</constant>,
49 <constant>SD_EVENT_RUNNING</constant>,
50 <constant>SD_EVENT_EXITING</constant>,
51 <constant>SD_EVENT_FINISHED</constant>,
55 <funcdef>int <function>sd_event_prepare</function></funcdef>
56 <paramdef>sd_event *<parameter>event</parameter></paramdef>
60 <funcdef>int <function>sd_event_wait</function></funcdef>
61 <paramdef>sd_event *<parameter>event</parameter></paramdef>
62 <paramdef>uint64_t <parameter>usec</parameter></paramdef>
66 <funcdef>int <function>sd_event_dispatch</function></funcdef>
67 <paramdef>sd_event *<parameter>event</parameter></paramdef>
71 <funcdef>int <function>sd_event_get_state</function></funcdef>
72 <paramdef>sd_event *<parameter>event</parameter></paramdef>
76 <funcdef>int <function>sd_event_get_iteration</function></funcdef>
77 <paramdef>sd_event *<parameter>event</parameter></paramdef>
78 <paramdef>uint64_t *<parameter>ret</parameter></paramdef>
85 <title>Description</title>
87 <para>The low-level <function>sd_event_prepare()</function>,
88 <function>sd_event_wait()</function> and
89 <function>sd_event_dispatch()</function> functions may be used to
90 execute specific phases of an event loop. See
91 <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>
93 <citerefentry><refentrytitle>sd_event_loop</refentrytitle><manvolnum>3</manvolnum></citerefentry>
94 for higher-level functions that execute individual but complete
95 iterations of an event loop or run it continuously.</para>
97 <para><function>sd_event_prepare()</function> checks for pending
98 events and arms necessary timers. If any events are ready to be
99 processed ("pending"), it returns a positive, non-zero value, and the caller
100 should process these events with
101 <function>sd_event_dispatch()</function>.</para>
103 <para><function>sd_event_dispatch()</function> dispatches the
104 highest priority event source that has a pending event. On
105 success, <function>sd_event_dispatch()</function> returns either
106 zero, which indicates that no further event sources may be
107 dispatched and exiting of the event loop was requested via
108 <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>;
109 or a positive non-zero value, which means that an event source was
110 dispatched and the loop returned to its initial state, and the
111 caller should initiate the next event loop iteration by invoking
112 <function>sd_event_prepare()</function> again.</para>
114 <para>In case <function>sd_event_prepare()</function> returned
115 zero, <function>sd_event_wait()</function> should be called to
116 wait for further events or a timeout. If any events are ready to
117 be processed, it returns a positive, non-zero value, and the
118 events should be dispatched with
119 <function>sd_event_dispatch()</function>. Otherwise, the event
120 loop returned to its initial state and the next event loop
121 iteration should be initiated by invoking
122 <function>sd_event_prepare()</function> again.</para>
124 <para><function>sd_event_get_state()</function> may be used to
125 determine the state the event loop is currently in. It returns one
126 of the states described below.</para>
128 <para><function>sd_event_get_iteration()</function> may be used to determine the current iteration of the event
129 loop. It returns an unsigned 64bit integer containing a counter that increases monotonically with each iteration of
130 the event loop, starting with 0. The counter is increased at the time of the
131 <function>sd_event_prepare()</function> invocation.</para>
133 <para>All five functions take, as the first argument, the event loop object <parameter>event</parameter> that has
134 been created with <function>sd_event_new()</function>. The timeout for <function>sd_event_wait()</function> is
135 specified in <parameter>usec</parameter> in microseconds. <constant>(uint64_t) -1</constant> may be used to
136 specify an infinite timeout.</para>
140 <title>State Machine</title>
142 <para>The event loop knows the following states, that may be
143 queried with <function>sd_event_get_state()</function>.</para>
147 <term><constant>SD_EVENT_INITIAL</constant></term>
149 <listitem><para>The initial state the event loop is in,
150 before each event loop iteration. Use
151 <function>sd_event_prepare()</function> to transition the
152 event loop into the <constant>SD_EVENT_ARMED</constant> or
153 <constant>SD_EVENT_PENDING</constant> states.</para></listitem>
157 <term><constant>SD_EVENT_PREPARING</constant></term>
159 <listitem><para>An event source is currently being prepared,
160 i.e. the preparation handler is currently being executed, as
162 <citerefentry><refentrytitle>sd_event_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This
163 state is only seen in the event source preparation handler
164 that is invoked from the
165 <function>sd_event_prepare()</function> call and is
166 immediately followed by <constant>SD_EVENT_ARMED</constant> or
167 <constant>SD_EVENT_PENDING</constant>.</para></listitem>
171 <term><constant>SD_EVENT_ARMED</constant></term>
173 <listitem><para><function>sd_event_prepare()</function> has
174 been called and no event sources were ready to be
175 dispatched. Use <function>sd_event_wait()</function> to wait
176 for new events, and transition into
177 <constant>SD_EVENT_PENDING</constant> or back into
178 <constant>SD_EVENT_INITIAL</constant>.</para></listitem>
182 <term><constant>SD_EVENT_PENDING</constant></term>
184 <listitem><para><function>sd_event_prepare()</function> or
185 <function>sd_event_wait()</function> have been called and
186 there were event sources with events pending. Use
187 <function>sd_event_dispatch()</function> to dispatch the
188 highest priority event source and transition back to
189 <constant>SD_EVENT_INITIAL</constant>, or
190 <constant>SD_EVENT_FINISHED</constant>.</para></listitem>
194 <term><constant>SD_EVENT_RUNNING</constant></term>
196 <listitem><para>A regular event source is currently being
197 dispatched. This state is only seen in the event source
198 handler that is invoked from the
199 <function>sd_event_dispatch()</function> call, and is
200 immediately followed by <constant>SD_EVENT_INITIAL</constant>
201 or <constant>SD_EVENT_FINISHED</constant> as soon the event
202 source handler returns. Note that during dispatching of exit
203 event sources the <constant>SD_EVENT_EXITING</constant> state
204 is seen instead.</para></listitem>
208 <term><constant>SD_EVENT_EXITING</constant></term>
210 <listitem><para>Similar to
211 <constant>SD_EVENT_RUNNING</constant> but is the state in
212 effect while dispatching exit event sources. It is followed by
213 <constant>SD_EVENT_INITIAL</constant> or
214 <constant>SD_EVENT_FINISHED</constant> as soon as the event
215 handler returns.</para></listitem>
219 <term><constant>SD_EVENT_FINISHED</constant></term>
221 <listitem><para>The event loop has exited. All exit event
222 sources have run. If the event loop is in this state it serves
223 no purpose anymore, and should be freed.</para></listitem>
228 <para>A simplified flow chart of the states and the calls to
229 transition between them is shown below. Note that
230 <constant>SD_EVENT_PREPARING</constant>,
231 <constant>SD_EVENT_RUNNING</constant> and
232 <constant>SD_EVENT_EXITING</constant> are not shown here.</para>
235 INITIAL -<---<---<---<---<---<---<---<---<---<---<---<---\
240 sd_event_prepare() >--->--->--->--->- ARMED |
245 PENDING <---<---<---<---<---< sd_event_wait() >--->--->--+
250 sd_event_dispatch() >--->--->--->--->--->--->--->--->--->--->/
260 <title>Return Value</title>
262 <para>On success, these functions return 0 or a positive integer.
263 On failure, they return a negative errno-style error code. In case
264 of <function>sd_event_prepare()</function> and
265 <function>sd_event_wait()</function>, a positive, non-zero return
266 code indicates that events are ready to be processed and zero
267 indicates that no events are ready. In case of
268 <function>sd_event_dispatch()</function>, a positive, non-zero
269 return code indicates that the event loop returned to its initial
270 state and zero indicates the event loop has
271 exited. <function>sd_event_get_state()</function> returns a
272 positive or zero state on success.</para>
276 <title>Errors</title>
278 <para>Returned errors may indicate the following problems:</para>
282 <term><constant>-EINVAL</constant></term>
284 <listitem><para>The <parameter>event</parameter> parameter is
285 invalid or <constant>NULL</constant>.</para></listitem>
289 <term><constant>-EBUSY</constant></term>
291 <listitem><para>The event loop object is not in the right
292 state.</para></listitem>
296 <term><constant>-ESTALE</constant></term>
298 <listitem><para>The event loop is already terminated.</para></listitem>
303 <term><constant>-ECHILD</constant></term>
305 <listitem><para>The event loop has been created in a different process.</para></listitem>
311 <para>Other errors are possible, too.</para>
314 <xi:include href="libelogind-pkgconfig.xml" />
317 <title>See Also</title>
320 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
321 <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
322 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
323 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
324 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
325 <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
326 <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
327 <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
328 <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
329 <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
330 <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>