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_get_iteration</refname>
51 <refname>SD_EVENT_INITIAL</refname>
52 <refname>SD_EVENT_PREPARING</refname>
53 <refname>SD_EVENT_ARMED</refname>
54 <refname>SD_EVENT_PENDING</refname>
55 <refname>SD_EVENT_RUNNING</refname>
56 <refname>SD_EVENT_EXITING</refname>
57 <refname>SD_EVENT_FINISHED</refname>
59 <refpurpose>Low-level event loop operations</refpurpose>
64 <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo>
66 <funcsynopsisinfo><token>enum</token> {
67 <constant>SD_EVENT_INITIAL</constant>,
68 <constant>SD_EVENT_PREPARING</constant>,
69 <constant>SD_EVENT_ARMED</constant>,
70 <constant>SD_EVENT_PENDING</constant>,
71 <constant>SD_EVENT_RUNNING</constant>,
72 <constant>SD_EVENT_EXITING</constant>,
73 <constant>SD_EVENT_FINISHED</constant>,
77 <funcdef>int <function>sd_event_prepare</function></funcdef>
78 <paramdef>sd_event *<parameter>event</parameter></paramdef>
82 <funcdef>int <function>sd_event_wait</function></funcdef>
83 <paramdef>sd_event *<parameter>event</parameter></paramdef>
84 <paramdef>uint64_t <parameter>usec</parameter></paramdef>
88 <funcdef>int <function>sd_event_dispatch</function></funcdef>
89 <paramdef>sd_event *<parameter>event</parameter></paramdef>
93 <funcdef>int <function>sd_event_get_state</function></funcdef>
94 <paramdef>sd_event *<parameter>event</parameter></paramdef>
98 <funcdef>int <function>sd_event_get_iteration</function></funcdef>
99 <paramdef>sd_event *<parameter>event</parameter></paramdef>
100 <paramdef>uint64_t *<parameter>ret</parameter></paramdef>
107 <title>Description</title>
109 <para>The low-level <function>sd_event_prepare()</function>,
110 <function>sd_event_wait()</function> and
111 <function>sd_event_dispatch()</function> functions may be used to
112 execute specific phases of an event loop. See
113 <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>
115 <citerefentry><refentrytitle>sd_event_loop</refentrytitle><manvolnum>3</manvolnum></citerefentry>
116 for higher-level functions that execute individual but complete
117 iterations of an event loop or run it continuously.</para>
119 <para><function>sd_event_prepare()</function> checks for pending
120 events and arms necessary timers. If any events are ready to be
121 processed ("pending"), it returns a positive, non-zero value, and the caller
122 should process these events with
123 <function>sd_event_dispatch()</function>.</para>
125 <para><function>sd_event_dispatch()</function> dispatches the
126 highest priority event source that has a pending event. On
127 success, <function>sd_event_dispatch()</function> returns either
128 zero, which indicates that no further event sources may be
129 dispatched and exiting of the event loop was requested via
130 <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>;
131 or a positive non-zero value, which means that an event source was
132 dispatched and the loop returned to its initial state, and the
133 caller should initiate the next event loop iteration by invoking
134 <function>sd_event_prepare()</function> again.</para>
136 <para>In case <function>sd_event_prepare()</function> returned
137 zero, <function>sd_event_wait()</function> should be called to
138 wait for further events or a timeout. If any events are ready to
139 be processed, it returns a positive, non-zero value, and the
140 events should be dispatched with
141 <function>sd_event_dispatch()</function>. Otherwise, the event
142 loop returned to its initial state and the next event loop
143 iteration should be initiated by invoking
144 <function>sd_event_prepare()</function> again.</para>
146 <para><function>sd_event_get_state()</function> may be used to
147 determine the state the event loop is currently in. It returns one
148 of the states described below.</para>
150 <para><function>sd_event_get_iteration()</function> may be used to determine the current iteration of the event
151 loop. It returns an unsigned 64bit integer containing a counter that increases monotonically with each iteration of
152 the event loop, starting with 0. The counter is increased at the time of the
153 <function>sd_event_prepare()</function> invocation.</para>
155 <para>All five functions take, as the first argument, the event loop object <parameter>event</parameter> that has
156 been created with <function>sd_event_new()</function>. The timeout for <function>sd_event_wait()</function> is
157 specified in <parameter>usec</parameter> in microseconds. <constant>(uint64_t) -1</constant> may be used to
158 specify an infinite timeout.</para>
162 <title>State Machine</title>
164 <para>The event loop knows the following states, that may be
165 queried with <function>sd_event_get_state()</function>.</para>
169 <term><constant>SD_EVENT_INITIAL</constant></term>
171 <listitem><para>The initial state the event loop is in,
172 before each event loop iteration. Use
173 <function>sd_event_prepare()</function> to transition the
174 event loop into the <constant>SD_EVENT_ARMED</constant> or
175 <constant>SD_EVENT_PENDING</constant> states.</para></listitem>
179 <term><constant>SD_EVENT_PREPARING</constant></term>
181 <listitem><para>An event source is currently being prepared,
182 i.e. the preparation handler is currently being executed, as
184 <citerefentry><refentrytitle>sd_event_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This
185 state is only seen in the event source preparation handler
186 that is invoked from the
187 <function>sd_event_prepare()</function> call and is
188 immediately followed by <constant>SD_EVENT_ARMED</constant> or
189 <constant>SD_EVENT_PENDING</constant>.</para></listitem>
193 <term><constant>SD_EVENT_ARMED</constant></term>
195 <listitem><para><function>sd_event_prepare()</function> has
196 been called and no event sources were ready to be
197 dispatched. Use <function>sd_event_wait()</function> to wait
198 for new events, and transition into
199 <constant>SD_EVENT_PENDING</constant> or back into
200 <constant>SD_EVENT_INITIAL</constant>.</para></listitem>
204 <term><constant>SD_EVENT_PENDING</constant></term>
206 <listitem><para><function>sd_event_prepare()</function> or
207 <function>sd_event_wait()</function> have been called and
208 there were event sources with events pending. Use
209 <function>sd_event_dispatch()</function> to dispatch the
210 highest priority event source and transition back to
211 <constant>SD_EVENT_INITIAL</constant>, or
212 <constant>SD_EVENT_FINISHED</constant>.</para></listitem>
216 <term><constant>SD_EVENT_RUNNING</constant></term>
218 <listitem><para>A regular event source is currently being
219 dispatched. This state is only seen in the event source
220 handler that is invoked from the
221 <function>sd_event_dispatch()</function> call, and is
222 immediately followed by <constant>SD_EVENT_INITIAL</constant>
223 or <constant>SD_EVENT_FINISHED</constant> as soon the event
224 source handler returns. Note that during dispatching of exit
225 event sources the <constant>SD_EVENT_EXITING</constant> state
226 is seen instead.</para></listitem>
230 <term><constant>SD_EVENT_EXITING</constant></term>
232 <listitem><para>Similar to
233 <constant>SD_EVENT_RUNNING</constant> but is the state in
234 effect while dispatching exit event sources. It is followed by
235 <constant>SD_EVENT_INITIAL</constant> or
236 <constant>SD_EVENT_FINISHED</constant> as soon as the event
237 handler returns.</para></listitem>
241 <term><constant>SD_EVENT_FINISHED</constant></term>
243 <listitem><para>The event loop has exited. All exit event
244 sources have run. If the event loop is in this state it serves
245 no purpose anymore, and should be freed.</para></listitem>
250 <para>A simplified flow chart of the states and the calls to
251 transition between them is shown below. Note that
252 <constant>SD_EVENT_PREPARING</constant>,
253 <constant>SD_EVENT_RUNNING</constant> and
254 <constant>SD_EVENT_EXITING</constant> are not shown here.</para>
257 INITIAL -<---<---<---<---<---<---<---<---<---<---<---<---\
262 sd_event_prepare() >--->--->--->--->- ARMED |
267 PENDING <---<---<---<---<---< sd_event_wait() >--->--->--+
272 sd_event_dispatch() >--->--->--->--->--->--->--->--->--->--->/
282 <title>Return Value</title>
284 <para>On success, these functions return 0 or a positive integer.
285 On failure, they return a negative errno-style error code. In case
286 of <function>sd_event_prepare()</function> and
287 <function>sd_event_wait()</function>, a positive, non-zero return
288 code indicates that events are ready to be processed and zero
289 indicates that no events are ready. In case of
290 <function>sd_event_dispatch()</function>, a positive, non-zero
291 return code indicates that the event loop returned to its initial
292 state and zero indicates the event loop has
293 exited. <function>sd_event_get_state()</function> returns a
294 positive or zero state on success.</para>
298 <title>Errors</title>
300 <para>Returned errors may indicate the following problems:</para>
304 <term><constant>-EINVAL</constant></term>
306 <listitem><para>The <parameter>event</parameter> parameter is
307 invalid or <constant>NULL</constant>.</para></listitem>
311 <term><constant>-EBUSY</constant></term>
313 <listitem><para>The event loop object is not in the right
314 state.</para></listitem>
318 <term><constant>-ESTALE</constant></term>
320 <listitem><para>The event loop is already terminated.</para></listitem>
325 <term><constant>-ECHILD</constant></term>
327 <listitem><para>The event loop has been created in a different process.</para></listitem>
333 <para>Other errors are possible, too.</para>
336 <xi:include href="libelogind-pkgconfig.xml" />
339 <title>See Also</title>
342 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
343 <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
344 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
345 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
346 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
347 <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
348 <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
349 <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
350 <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
351 <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
352 <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>