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