man/sd_event_wait.xml

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