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 This file is part of systemd.
10 Copyright 2015 Zbigniew Jędrzejewski-Szmek
13 <refentry id=
"sd_event_wait" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
16 <title>sd_event_wait
</title>
17 <productname>systemd
</productname>
21 <contrib>Developer
</contrib>
22 <firstname>Tom
</firstname>
23 <surname>Gundersen
</surname>
24 <email>teg@jklm.no
</email>
30 <refentrytitle>sd_event_wait
</refentrytitle>
31 <manvolnum>3</manvolnum>
35 <refname>sd_event_wait
</refname>
36 <refname>sd_event_prepare
</refname>
37 <refname>sd_event_dispatch
</refname>
38 <refname>sd_event_get_state
</refname>
39 <refname>sd_event_get_iteration
</refname>
40 <refname>SD_EVENT_INITIAL
</refname>
41 <refname>SD_EVENT_PREPARING
</refname>
42 <refname>SD_EVENT_ARMED
</refname>
43 <refname>SD_EVENT_PENDING
</refname>
44 <refname>SD_EVENT_RUNNING
</refname>
45 <refname>SD_EVENT_EXITING
</refname>
46 <refname>SD_EVENT_FINISHED
</refname>
48 <refpurpose>Low-level event loop operations
</refpurpose>
53 <funcsynopsisinfo>#include
<systemd/sd-event.h
></funcsynopsisinfo>
55 <funcsynopsisinfo><token>enum
</token> {
56 <constant>SD_EVENT_INITIAL
</constant>,
57 <constant>SD_EVENT_PREPARING
</constant>,
58 <constant>SD_EVENT_ARMED
</constant>,
59 <constant>SD_EVENT_PENDING
</constant>,
60 <constant>SD_EVENT_RUNNING
</constant>,
61 <constant>SD_EVENT_EXITING
</constant>,
62 <constant>SD_EVENT_FINISHED
</constant>,
66 <funcdef>int
<function>sd_event_prepare
</function></funcdef>
67 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
71 <funcdef>int
<function>sd_event_wait
</function></funcdef>
72 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
73 <paramdef>uint64_t
<parameter>usec
</parameter></paramdef>
77 <funcdef>int
<function>sd_event_dispatch
</function></funcdef>
78 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
82 <funcdef>int
<function>sd_event_get_state
</function></funcdef>
83 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
87 <funcdef>int
<function>sd_event_get_iteration
</function></funcdef>
88 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
89 <paramdef>uint64_t *
<parameter>ret
</parameter></paramdef>
96 <title>Description
</title>
98 <para>The low-level
<function>sd_event_prepare()
</function>,
99 <function>sd_event_wait()
</function> and
100 <function>sd_event_dispatch()
</function> functions may be used to
101 execute specific phases of an event loop. See
102 <citerefentry><refentrytitle>sd_event_run
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
104 <citerefentry><refentrytitle>sd_event_loop
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
105 for higher-level functions that execute individual but complete
106 iterations of an event loop or run it continuously.
</para>
108 <para><function>sd_event_prepare()
</function> checks for pending
109 events and arms necessary timers. If any events are ready to be
110 processed (
"pending"), it returns a positive, non-zero value, and the caller
111 should process these events with
112 <function>sd_event_dispatch()
</function>.
</para>
114 <para><function>sd_event_dispatch()
</function> dispatches the
115 highest priority event source that has a pending event. On
116 success,
<function>sd_event_dispatch()
</function> returns either
117 zero, which indicates that no further event sources may be
118 dispatched and exiting of the event loop was requested via
119 <citerefentry><refentrytitle>sd_event_exit
</refentrytitle><manvolnum>3</manvolnum></citerefentry>;
120 or a positive non-zero value, which means that an event source was
121 dispatched and the loop returned to its initial state, and the
122 caller should initiate the next event loop iteration by invoking
123 <function>sd_event_prepare()
</function> again.
</para>
125 <para>In case
<function>sd_event_prepare()
</function> returned
126 zero,
<function>sd_event_wait()
</function> should be called to
127 wait for further events or a timeout. If any events are ready to
128 be processed, it returns a positive, non-zero value, and the
129 events should be dispatched with
130 <function>sd_event_dispatch()
</function>. Otherwise, the event
131 loop returned to its initial state and the next event loop
132 iteration should be initiated by invoking
133 <function>sd_event_prepare()
</function> again.
</para>
135 <para><function>sd_event_get_state()
</function> may be used to
136 determine the state the event loop is currently in. It returns one
137 of the states described below.
</para>
139 <para><function>sd_event_get_iteration()
</function> may be used to determine the current iteration of the event
140 loop. It returns an unsigned
64bit integer containing a counter that increases monotonically with each iteration of
141 the event loop, starting with
0. The counter is increased at the time of the
142 <function>sd_event_prepare()
</function> invocation.
</para>
144 <para>All five functions take, as the first argument, the event loop object
<parameter>event
</parameter> that has
145 been created with
<function>sd_event_new()
</function>. The timeout for
<function>sd_event_wait()
</function> is
146 specified in
<parameter>usec
</parameter> in microseconds.
<constant>(uint64_t) -
1</constant> may be used to
147 specify an infinite timeout.
</para>
151 <title>State Machine
</title>
153 <para>The event loop knows the following states, that may be
154 queried with
<function>sd_event_get_state()
</function>.
</para>
158 <term><constant>SD_EVENT_INITIAL
</constant></term>
160 <listitem><para>The initial state the event loop is in,
161 before each event loop iteration. Use
162 <function>sd_event_prepare()
</function> to transition the
163 event loop into the
<constant>SD_EVENT_ARMED
</constant> or
164 <constant>SD_EVENT_PENDING
</constant> states.
</para></listitem>
168 <term><constant>SD_EVENT_PREPARING
</constant></term>
170 <listitem><para>An event source is currently being prepared,
171 i.e. the preparation handler is currently being executed, as
173 <citerefentry><refentrytitle>sd_event_set_prepare
</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This
174 state is only seen in the event source preparation handler
175 that is invoked from the
176 <function>sd_event_prepare()
</function> call and is
177 immediately followed by
<constant>SD_EVENT_ARMED
</constant> or
178 <constant>SD_EVENT_PENDING
</constant>.
</para></listitem>
182 <term><constant>SD_EVENT_ARMED
</constant></term>
184 <listitem><para><function>sd_event_prepare()
</function> has
185 been called and no event sources were ready to be
186 dispatched. Use
<function>sd_event_wait()
</function> to wait
187 for new events, and transition into
188 <constant>SD_EVENT_PENDING
</constant> or back into
189 <constant>SD_EVENT_INITIAL
</constant>.
</para></listitem>
193 <term><constant>SD_EVENT_PENDING
</constant></term>
195 <listitem><para><function>sd_event_prepare()
</function> or
196 <function>sd_event_wait()
</function> have been called and
197 there were event sources with events pending. Use
198 <function>sd_event_dispatch()
</function> to dispatch the
199 highest priority event source and transition back to
200 <constant>SD_EVENT_INITIAL
</constant>, or
201 <constant>SD_EVENT_FINISHED
</constant>.
</para></listitem>
205 <term><constant>SD_EVENT_RUNNING
</constant></term>
207 <listitem><para>A regular event source is currently being
208 dispatched. This state is only seen in the event source
209 handler that is invoked from the
210 <function>sd_event_dispatch()
</function> call, and is
211 immediately followed by
<constant>SD_EVENT_INITIAL
</constant>
212 or
<constant>SD_EVENT_FINISHED
</constant> as soon the event
213 source handler returns. Note that during dispatching of exit
214 event sources the
<constant>SD_EVENT_EXITING
</constant> state
215 is seen instead.
</para></listitem>
219 <term><constant>SD_EVENT_EXITING
</constant></term>
221 <listitem><para>Similar to
222 <constant>SD_EVENT_RUNNING
</constant> but is the state in
223 effect while dispatching exit event sources. It is followed by
224 <constant>SD_EVENT_INITIAL
</constant> or
225 <constant>SD_EVENT_FINISHED
</constant> as soon as the event
226 handler returns.
</para></listitem>
230 <term><constant>SD_EVENT_FINISHED
</constant></term>
232 <listitem><para>The event loop has exited. All exit event
233 sources have run. If the event loop is in this state it serves
234 no purpose anymore, and should be freed.
</para></listitem>
239 <para>A simplified flow chart of the states and the calls to
240 transition between them is shown below. Note that
241 <constant>SD_EVENT_PREPARING
</constant>,
242 <constant>SD_EVENT_RUNNING
</constant> and
243 <constant>SD_EVENT_EXITING
</constant> are not shown here.
</para>
246 INITIAL -
<---
<---
<---
<---
<---
<---
<---
<---
<---
<---
<---
<---\
251 sd_event_prepare()
>---
>---
>---
>---
>- ARMED |
256 PENDING
<---
<---
<---
<---
<---
< sd_event_wait()
>---
>---
>--+
261 sd_event_dispatch()
>---
>---
>---
>---
>---
>---
>---
>---
>---
>---
>/
271 <title>Return Value
</title>
273 <para>On success, these functions return
0 or a positive integer.
274 On failure, they return a negative errno-style error code. In case
275 of
<function>sd_event_prepare()
</function> and
276 <function>sd_event_wait()
</function>, a positive, non-zero return
277 code indicates that events are ready to be processed and zero
278 indicates that no events are ready. In case of
279 <function>sd_event_dispatch()
</function>, a positive, non-zero
280 return code indicates that the event loop returned to its initial
281 state and zero indicates the event loop has
282 exited.
<function>sd_event_get_state()
</function> returns a
283 positive or zero state on success.
</para>
287 <title>Errors
</title>
289 <para>Returned errors may indicate the following problems:
</para>
293 <term><constant>-EINVAL
</constant></term>
295 <listitem><para>The
<parameter>event
</parameter> parameter is
296 invalid or
<constant>NULL
</constant>.
</para></listitem>
300 <term><constant>-EBUSY
</constant></term>
302 <listitem><para>The event loop object is not in the right
303 state.
</para></listitem>
307 <term><constant>-ESTALE
</constant></term>
309 <listitem><para>The event loop is already terminated.
</para></listitem>
314 <term><constant>-ECHILD
</constant></term>
316 <listitem><para>The event loop has been created in a different process.
</para></listitem>
322 <para>Other errors are possible, too.
</para>
325 <xi:include href=
"libsystemd-pkgconfig.xml" />
328 <title>See Also
</title>
331 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
332 <citerefentry><refentrytitle>sd_event_new
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
333 <citerefentry><refentrytitle>sd_event_add_io
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
334 <citerefentry><refentrytitle>sd_event_add_time
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
335 <citerefentry><refentrytitle>sd_event_add_signal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
336 <citerefentry><refentrytitle>sd_event_add_defer
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
337 <citerefentry><refentrytitle>sd_event_add_exit
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
338 <citerefentry><refentrytitle>sd_event_add_post
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
339 <citerefentry><refentrytitle>sd_event_run
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
340 <citerefentry><refentrytitle>sd_event_get_fd
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
341 <citerefentry><refentrytitle>sd_event_source_set_prepare
</refentrytitle><manvolnum>3</manvolnum></citerefentry>