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