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 This file is part of systemd.
8 Copyright 2015 Zbigniew Jędrzejewski-Szmek
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id=
"sd_event_wait" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
27 <title>sd_event_wait
</title>
28 <productname>systemd
</productname>
32 <contrib>Developer
</contrib>
33 <firstname>Tom
</firstname>
34 <surname>Gundersen
</surname>
35 <email>teg@jklm.no
</email>
41 <refentrytitle>sd_event_wait
</refentrytitle>
42 <manvolnum>3</manvolnum>
46 <refname>sd_event_wait
</refname>
47 <refname>sd_event_prepare
</refname>
48 <refname>sd_event_dispatch
</refname>
49 <refname>sd_event_get_state
</refname>
50 <refname>SD_EVENT_INITIAL
</refname>
51 <refname>SD_EVENT_PREPARING
</refname>
52 <refname>SD_EVENT_ARMED
</refname>
53 <refname>SD_EVENT_PENDING
</refname>
54 <refname>SD_EVENT_RUNNING
</refname>
55 <refname>SD_EVENT_EXITING
</refname>
56 <refname>SD_EVENT_FINISHED
</refname>
58 <refpurpose>Low-level event loop operations
</refpurpose>
63 <funcsynopsisinfo>#include
<systemd/sd-event.h
></funcsynopsisinfo>
65 <funcsynopsisinfo><token>enum
</token> {
66 <constant>SD_EVENT_INITIAL
</constant>,
67 <constant>SD_EVENT_PREPARING
</constant>,
68 <constant>SD_EVENT_ARMED
</constant>,
69 <constant>SD_EVENT_PENDING
</constant>,
70 <constant>SD_EVENT_RUNNING
</constant>,
71 <constant>SD_EVENT_EXITING
</constant>,
72 <constant>SD_EVENT_FINISHED
</constant>,
76 <funcdef>int
<function>sd_event_prepare
</function></funcdef>
77 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
81 <funcdef>int
<function>sd_event_wait
</function></funcdef>
82 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
83 <paramdef>uint64_t
<parameter>usec
</parameter></paramdef>
87 <funcdef>int
<function>sd_event_dispatch
</function></funcdef>
88 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
92 <funcdef>int
<function>sd_event_get_state
</function></funcdef>
93 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
100 <title>Description
</title>
102 <para>The low-level
<function>sd_event_prepare()
</function>,
103 <function>sd_event_wait()
</function> and
104 <function>sd_event_dispatch()
</function> functions may be used to
105 execute specific phases of an event loop. See
106 <citerefentry><refentrytitle>sd_event_run
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
108 <citerefentry><refentrytitle>sd_event_loop
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
109 for higher-level functions that execute individual but complete
110 iterations of an event loop or run it continously.
</para>
112 <para><function>sd_event_prepare()
</function> checks for pending
113 events and arms necessary timers. If any events are ready to be
114 processed (
"pending"), it returns a positive, non-zero value, and the caller
115 should process these events with
116 <function>sd_event_dispatch()
</function>.
</para>
118 <para><function>sd_event_dispatch()
</function> dispatches the
119 highest priority event source that has a pending event. On
120 success,
<function>sd_event_dispatch()
</function> returns either
121 zero, which indicates that no further event sources may be
122 dispatched and exiting of the event loop was requested via
123 <citerefentry><refentrytitle>sd_event_exit
</refentrytitle><manvolnum>3</manvolnum></citerefentry>;
124 or a positive non-zero value, which means that an event source was
125 dispatched and the loop returned to its initial state, and the
126 caller should initiate the next event loop iteration by invoking
127 <function>sd_event_prepare()
</function> again.
</para>
129 <para>In case
<function>sd_event_prepare()
</function> returned
130 zero,
<function>sd_event_wait()
</function> should be called to
131 wait for further events or a timeout. If any events are ready to
132 be processed, it returns a positive, non-zero value, and the
133 events should be dispatched with
134 <function>sd_event_dispatch()
</function>. Otherwise, the event
135 loop returned to its initial state and the next event loop
136 iteration should be initiated by invoking
137 <function>sd_event_prepare()
</function> again.
</para>
139 <para><function>sd_event_get_state()
</function> may be used to
140 determine the state the event loop is currently in. It returns one
141 of the states described below.
</para>
143 <para>All four functions take, as the first argument, the event
144 loop object
<parameter>event
</parameter> that has been created
145 with
<function>sd_event_new()
</function>. The timeout for
146 <function>sd_event_wait()
</function> is specified in
147 <parameter>usec
</parameter> in milliseconds.
<constant>(uint64_t)
148 -
1</constant> may be used to specify an infinite timeout.
</para>
152 <title>State Machine
</title>
154 <para>The event loop knows the following states, that may be
155 queried with
<function>sd_event_get_state()
</function>.
</para>
159 <term><constant>SD_EVENT_INITIAL
</constant></term>
161 <listitem><para>The initial state the event loop is in,
162 before each event loop iteration. Use
163 <function>sd_event_prepare()
</function> to transition the
164 event loop into the
<constant>SD_EVENT_ARMED
</constant> or
165 <constant>SD_EVENT_PENDING
</constant> states.
</para></listitem>
169 <term><constant>SD_EVENT_PREPARING
</constant></term>
171 <listitem><para>An event source is currently being prepared,
172 i.e. the preparation handler is currently being excuted, as
174 <citerefentry><refentrytitle>sd_event_set_prepare
</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This
175 state is only seen in the event source preparation handler
176 that is invoked from the
177 <function>sd_event_prepare()
</function> call and is
178 immediately followed by
<constant>SD_EVENT_ARMED
</constant> or
179 <constant>SD_EVENT_PENDING
</constant>.
</para></listitem>
183 <term><constant>SD_EVENT_ARMED
</constant></term>
185 <listitem><para><function>sd_event_prepare()
</function> has
186 been called and no event sources were ready to be
187 dispatched. Use
<function>sd_event_wait()
</function> to wait
188 for new events, and transition into
189 <constant>SD_EVENT_PENDING
</constant> or back into
190 <constant>SD_EVENT_INITIAL
</constant>.
</para></listitem>
194 <term><constant>SD_EVENT_PENDING
</constant></term>
196 <listitem><para><function>sd_event_prepare()
</function> or
197 <function>sd_event_wait()
</function> have been called and
198 there were event sources with events pending. Use
199 <function>sd_event_dispatch()
</function> to dispatch the
200 highest priority event source and transition back to
201 <constant>SD_EVENT_INITIAL
</constant>, or
202 <constant>SD_EVENT_FINISHED
</constant>.
</para></listitem>
206 <term><constant>SD_EVENT_RUNNING
</constant></term>
208 <listitem><para>A regular event source is currently being
209 dispatched. This state is only seen in the event source
210 handler that is invoked from the
211 <function>sd_event_dispatch()
</function> call, and is
212 immediately followed by
<constant>SD_EVENT_INITIAL
</constant>
213 or
<constant>SD_EVENT_FINISHED
</constant> as soon the event
214 source handler returns. Note that during dispatching of exit
215 event sources the
<constant>SD_EVENT_EXITING
</constant> state
216 is seen instead.
</para></listitem>
220 <term><constant>SD_EVENT_EXITING
</constant></term>
222 <listitem><para>Similar to
223 <constant>SD_EVENT_RUNNING
</constant> but is the state in
224 effect while dispatching exit event sources. It is followed by
225 <constant>SD_EVENT_INITIAL
</constant> or
226 <constant>SD_EVENT_FINISHED
</constant> as soon as the event
227 handler returns.
</para></listitem>
231 <term><constant>SD_EVENT_FINISHED
</constant></term>
233 <listitem><para>The event loop has exited. All exit event
234 sources have run. If the event loop is in this state it serves
235 no purpose anymore, and should be freed.
</para></listitem>
240 <para>A simplified flow chart of the states and the calls to
241 transition between them is shown below. Note that
242 <constant>SD_EVENT_PREPARING
</constant>,
243 <constant>SD_EVENT_RUNNING
</constant> and
244 <constant>SD_EVENT_EXITING
</constant> are not shown here.
</para>
247 INITIAL -
<---
<---
<---
<---
<---
<---
<---
<---
<---
<---
<---
<---\
252 sd_event_prepare()
>---
>---
>---
>---
>- ARMED |
257 PENDING
<---
<---
<---
<---
<---
< sd_event_wait()
>---
>---
>--+
262 sd_event_dispatch()
>---
>---
>---
>---
>---
>---
>---
>---
>---
>---
>/
272 <title>Return Value
</title>
274 <para>On success, these functions return
0 or a positive integer.
275 On failure, they return a negative errno-style error code. In case
276 of
<function>sd_event_prepare()
</function> and
277 <function>sd_event_wait()
</function>, a positive, non-zero return
278 code indicates that events are ready to be processed and zero
279 indicates that no events are ready. In case of
280 <function>sd_event_dispatch()
</function>, a positive, non-zero
281 return code indicates that the event loop returned to its initial
282 state and zero indicates the event loop has
283 exited.
<function>sd_event_get_state()
</function> returns a
284 positive or zero state on success.
</para>
288 <title>Errors
</title>
290 <para>Returned errors may indicate the following problems:
</para>
294 <term><constant>-EINVAL
</constant></term>
296 <listitem><para>The
<parameter>event
</parameter> parameter is
297 invalid or
<constant>NULL
</constant>.
</para></listitem>
301 <term><constant>-EBUSY
</constant></term>
303 <listitem><para>The event loop object is not in the right
304 state.
</para></listitem>
308 <term><constant>-ESTALE
</constant></term>
310 <listitem><para>The event loop is already terminated.
</para></listitem>
315 <term><constant>-ECHILD
</constant></term>
317 <listitem><para>The event loop has been created in a different process.
</para></listitem>
323 <para>Other errors are possible, too.
</para>
326 <xi:include href=
"libsystemd-pkgconfig.xml" />
329 <title>See Also
</title>
332 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
333 <citerefentry><refentrytitle>sd_event_new
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
334 <citerefentry><refentrytitle>sd_event_add_io
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
335 <citerefentry><refentrytitle>sd_event_add_time
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
336 <citerefentry><refentrytitle>sd_event_add_signal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
337 <citerefentry><refentrytitle>sd_event_add_defer
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
338 <citerefentry><refentrytitle>sd_event_add_exit
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
339 <citerefentry><refentrytitle>sd_event_add_post
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
340 <citerefentry><refentrytitle>sd_event_run
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
341 <citerefentry><refentrytitle>sd_event_get_fd
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
342 <citerefentry><refentrytitle>sd_event_source_set_prepare
</refentrytitle><manvolnum>3</manvolnum></citerefentry>