man/sd_event_wait.xml

   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">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7
   8   This file is part of systemd.
   9
  10   Copyright 2015 Zbigniew Jędrzejewski-Szmek
  11
  12   systemd is free software; you can redistribute it and/or modify it
  13   under the terms of the GNU Lesser General Public License as published by
  14   the Free Software Foundation; either version 2.1 of the License, or
  15   (at your option) any later version.
  16
  17   systemd is distributed in the hope that it will be useful, but
  18   WITHOUT ANY WARRANTY; without even the implied warranty of
  19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  20   Lesser General Public License for more details.
  21
  22   You should have received a copy of the GNU Lesser General Public License
  23   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  24 -->
  25
  26 <refentry id="sd_event_wait" xmlns:xi="http://www.w3.org/2001/XInclude">
  27
  28   <refentryinfo>
  29     <title>sd_event_wait</title>
  30     <productname>systemd</productname>
  31
  32     <authorgroup>
  33       <author>
  34         <contrib>Developer</contrib>
  35         <firstname>Tom</firstname>
  36         <surname>Gundersen</surname>
  37         <email>teg@jklm.no</email>
  38       </author>
  39     </authorgroup>
  40   </refentryinfo>
  41
  42   <refmeta>
  43     <refentrytitle>sd_event_wait</refentrytitle>
  44     <manvolnum>3</manvolnum>
  45   </refmeta>
  46
  47   <refnamediv>
  48     <refname>sd_event_wait</refname>
  49     <refname>sd_event_prepare</refname>
  50     <refname>sd_event_dispatch</refname>
  51     <refname>sd_event_get_state</refname>
  52     <refname>sd_event_get_iteration</refname>
  53     <refname>SD_EVENT_INITIAL</refname>
  54     <refname>SD_EVENT_PREPARING</refname>
  55     <refname>SD_EVENT_ARMED</refname>
  56     <refname>SD_EVENT_PENDING</refname>
  57     <refname>SD_EVENT_RUNNING</refname>
  58     <refname>SD_EVENT_EXITING</refname>
  59     <refname>SD_EVENT_FINISHED</refname>
  60
  61     <refpurpose>Low-level event loop operations</refpurpose>
  62   </refnamediv>
  63
  64   <refsynopsisdiv>
  65     <funcsynopsis>
  66       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  67
  68       <funcsynopsisinfo><token>enum</token> {
  69         <constant>SD_EVENT_INITIAL</constant>,
  70         <constant>SD_EVENT_PREPARING</constant>,
  71         <constant>SD_EVENT_ARMED</constant>,
  72         <constant>SD_EVENT_PENDING</constant>,
  73         <constant>SD_EVENT_RUNNING</constant>,
  74         <constant>SD_EVENT_EXITING</constant>,
  75         <constant>SD_EVENT_FINISHED</constant>,
  76 };</funcsynopsisinfo>
  77
  78       <funcprototype>
  79         <funcdef>int <function>sd_event_prepare</function></funcdef>
  80         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  81       </funcprototype>
  82
  83       <funcprototype>
  84         <funcdef>int <function>sd_event_wait</function></funcdef>
  85         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  86         <paramdef>uint64_t <parameter>usec</parameter></paramdef>
  87       </funcprototype>
  88
  89       <funcprototype>
  90         <funcdef>int <function>sd_event_dispatch</function></funcdef>
  91         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  92       </funcprototype>
  93
  94       <funcprototype>
  95         <funcdef>int <function>sd_event_get_state</function></funcdef>
  96         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  97       </funcprototype>
  98
  99       <funcprototype>
 100         <funcdef>int <function>sd_event_get_iteration</function></funcdef>
 101         <paramdef>sd_event *<parameter>event</parameter></paramdef>
 102         <paramdef>uint64_t *<parameter>ret</parameter></paramdef>
 103       </funcprototype>
 104
 105     </funcsynopsis>
 106   </refsynopsisdiv>
 107
 108   <refsect1>
 109     <title>Description</title>
 110
 111     <para>The low-level <function>sd_event_prepare()</function>,
 112     <function>sd_event_wait()</function> and
 113     <function>sd_event_dispatch()</function> functions may be used to
 114     execute specific phases of an event loop. See
 115     <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 116     and
 117     <citerefentry><refentrytitle>sd_event_loop</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 118     for higher-level functions that execute individual but complete
 119     iterations of an event loop or run it continuously.</para>
 120
 121     <para><function>sd_event_prepare()</function> checks for pending
 122     events and arms necessary timers. If any events are ready to be
 123     processed ("pending"), it returns a positive, non-zero value, and the caller
 124     should process these events with
 125     <function>sd_event_dispatch()</function>.</para>
 126
 127     <para><function>sd_event_dispatch()</function> dispatches the
 128     highest priority event source that has a pending event. On
 129     success, <function>sd_event_dispatch()</function> returns either
 130     zero, which indicates that no further event sources may be
 131     dispatched and exiting of the event loop was requested via
 132     <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>;
 133     or a positive non-zero value, which means that an event source was
 134     dispatched and the loop returned to its initial state, and the
 135     caller should initiate the next event loop iteration by invoking
 136     <function>sd_event_prepare()</function> again.</para>
 137
 138     <para>In case <function>sd_event_prepare()</function> returned
 139     zero, <function>sd_event_wait()</function> should be called to
 140     wait for further events or a timeout. If any events are ready to
 141     be processed, it returns a positive, non-zero value, and the
 142     events should be dispatched with
 143     <function>sd_event_dispatch()</function>. Otherwise, the event
 144     loop returned to its initial state and the next event loop
 145     iteration should be initiated by invoking
 146     <function>sd_event_prepare()</function> again.</para>
 147
 148     <para><function>sd_event_get_state()</function> may be used to
 149     determine the state the event loop is currently in. It returns one
 150     of the states described below.</para>
 151
 152     <para><function>sd_event_get_iteration()</function> may be used to determine the current iteration of the event
 153     loop. It returns an unsigned 64bit integer containing a counter that increases monotonically with each iteration of
 154     the event loop, starting with 0. The counter is increased at the time of the
 155     <function>sd_event_prepare()</function> invocation.</para>
 156
 157     <para>All five functions take, as the first argument, the event loop object <parameter>event</parameter> that has
 158     been created with <function>sd_event_new()</function>. The timeout for <function>sd_event_wait()</function> is
 159     specified in <parameter>usec</parameter> in microseconds.  <constant>(uint64_t) -1</constant> may be used to
 160     specify an infinite timeout.</para>
 161 </refsect1>
 162
 163   <refsect1>
 164     <title>State Machine</title>
 165
 166     <para>The event loop knows the following states, that may be
 167     queried with <function>sd_event_get_state()</function>.</para>
 168
 169     <variablelist>
 170       <varlistentry>
 171         <term><constant>SD_EVENT_INITIAL</constant></term>
 172
 173         <listitem><para>The initial state the event loop is in,
 174         before each event loop iteration. Use
 175         <function>sd_event_prepare()</function> to transition the
 176         event loop into the <constant>SD_EVENT_ARMED</constant> or
 177         <constant>SD_EVENT_PENDING</constant> states.</para></listitem>
 178       </varlistentry>
 179
 180       <varlistentry>
 181         <term><constant>SD_EVENT_PREPARING</constant></term>
 182
 183         <listitem><para>An event source is currently being prepared,
 184         i.e. the preparation handler is currently being executed, as
 185         set with
 186         <citerefentry><refentrytitle>sd_event_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This
 187         state is only seen in the event source preparation handler
 188         that is invoked from the
 189         <function>sd_event_prepare()</function> call and is
 190         immediately followed by <constant>SD_EVENT_ARMED</constant> or
 191         <constant>SD_EVENT_PENDING</constant>.</para></listitem>
 192       </varlistentry>
 193
 194       <varlistentry>
 195         <term><constant>SD_EVENT_ARMED</constant></term>
 196
 197         <listitem><para><function>sd_event_prepare()</function> has
 198         been called and no event sources were ready to be
 199         dispatched. Use <function>sd_event_wait()</function> to wait
 200         for new events, and transition into
 201         <constant>SD_EVENT_PENDING</constant> or back into
 202         <constant>SD_EVENT_INITIAL</constant>.</para></listitem>
 203       </varlistentry>
 204
 205       <varlistentry>
 206         <term><constant>SD_EVENT_PENDING</constant></term>
 207
 208         <listitem><para><function>sd_event_prepare()</function> or
 209         <function>sd_event_wait()</function> have been called and
 210         there were event sources with events pending. Use
 211         <function>sd_event_dispatch()</function> to dispatch the
 212         highest priority event source and transition back to
 213         <constant>SD_EVENT_INITIAL</constant>, or
 214         <constant>SD_EVENT_FINISHED</constant>.</para></listitem>
 215       </varlistentry>
 216
 217       <varlistentry>
 218         <term><constant>SD_EVENT_RUNNING</constant></term>
 219
 220         <listitem><para>A regular event source is currently being
 221         dispatched. This state is only seen in the event source
 222         handler that is invoked from the
 223         <function>sd_event_dispatch()</function> call, and is
 224         immediately followed by <constant>SD_EVENT_INITIAL</constant>
 225         or <constant>SD_EVENT_FINISHED</constant> as soon the event
 226         source handler returns. Note that during dispatching of exit
 227         event sources the <constant>SD_EVENT_EXITING</constant> state
 228         is seen instead.</para></listitem>
 229       </varlistentry>
 230
 231       <varlistentry>
 232         <term><constant>SD_EVENT_EXITING</constant></term>
 233
 234         <listitem><para>Similar to
 235         <constant>SD_EVENT_RUNNING</constant> but is the state in
 236         effect while dispatching exit event sources. It is followed by
 237         <constant>SD_EVENT_INITIAL</constant> or
 238         <constant>SD_EVENT_FINISHED</constant> as soon as the event
 239         handler returns.</para></listitem>
 240       </varlistentry>
 241
 242       <varlistentry>
 243         <term><constant>SD_EVENT_FINISHED</constant></term>
 244
 245         <listitem><para>The event loop has exited. All exit event
 246         sources have run. If the event loop is in this state it serves
 247         no purpose anymore, and should be freed.</para></listitem>
 248       </varlistentry>
 249
 250     </variablelist>
 251
 252     <para>A simplified flow chart of the states and the calls to
 253     transition between them is shown below. Note that
 254     <constant>SD_EVENT_PREPARING</constant>,
 255     <constant>SD_EVENT_RUNNING</constant> and
 256     <constant>SD_EVENT_EXITING</constant> are not shown here.</para>
 257
 258     <programlisting>
 259           INITIAL -&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---\
 260              |                                                     |
 261              |                                                     ^
 262              |                                                     |
 263              v                 ret == 0                            |
 264       sd_event_prepare() &gt;---&gt;---&gt;---&gt;---&gt;- ARMED                  |
 265              |                                |                    ^
 266              | ret > 0                        |                    |
 267              |                                |                    |
 268              v                                v          ret == 0  |
 269           PENDING &lt;---&lt;---&lt;---&lt;---&lt;---&lt; sd_event_wait() &gt;---&gt;---&gt;--+
 270              |           ret > 0                                   ^
 271              |                                                     |
 272              |                                                     |
 273              v                                                     |
 274       sd_event_dispatch() &gt;---&gt;---&gt;---&gt;---&gt;---&gt;---&gt;---&gt;---&gt;---&gt;---&gt;/
 275              |                             ret > 0
 276              | ret == 0
 277              |
 278              v
 279           FINISHED
 280     </programlisting>
 281   </refsect1>
 282
 283   <refsect1>
 284     <title>Return Value</title>
 285
 286     <para>On success, these functions return 0 or a positive integer.
 287     On failure, they return a negative errno-style error code. In case
 288     of <function>sd_event_prepare()</function> and
 289     <function>sd_event_wait()</function>, a positive, non-zero return
 290     code indicates that events are ready to be processed and zero
 291     indicates that no events are ready. In case of
 292     <function>sd_event_dispatch()</function>, a positive, non-zero
 293     return code indicates that the event loop returned to its initial
 294     state and zero indicates the event loop has
 295     exited. <function>sd_event_get_state()</function> returns a
 296     positive or zero state on success.</para>
 297   </refsect1>
 298
 299   <refsect1>
 300     <title>Errors</title>
 301
 302     <para>Returned errors may indicate the following problems:</para>
 303
 304     <variablelist>
 305       <varlistentry>
 306         <term><constant>-EINVAL</constant></term>
 307
 308         <listitem><para>The <parameter>event</parameter> parameter is
 309         invalid or <constant>NULL</constant>.</para></listitem>
 310       </varlistentry>
 311
 312       <varlistentry>
 313         <term><constant>-EBUSY</constant></term>
 314
 315         <listitem><para>The event loop object is not in the right
 316         state.</para></listitem>
 317       </varlistentry>
 318
 319       <varlistentry>
 320         <term><constant>-ESTALE</constant></term>
 321
 322         <listitem><para>The event loop is already terminated.</para></listitem>
 323
 324       </varlistentry>
 325
 326       <varlistentry>
 327         <term><constant>-ECHILD</constant></term>
 328
 329         <listitem><para>The event loop has been created in a different process.</para></listitem>
 330
 331       </varlistentry>
 332
 333     </variablelist>
 334
 335     <para>Other errors are possible, too.</para>
 336   </refsect1>
 337
 338   <xi:include href="libelogind-pkgconfig.xml" />
 339
 340   <refsect1>
 341     <title>See Also</title>
 342
 343     <para>
 344       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 345       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 346       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 347       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 348       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 349       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 350       <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 351       <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 352       <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 353       <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 354       <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 355     </para>
 356   </refsect1>
 357
 358 </refentry>