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