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