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