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-or-later -->
   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 64-bit 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>
 149
 150         <xi:include href="version-info.xml" xpointer="v229"/></listitem>
 151       </varlistentry>
 152
 153       <varlistentry>
 154         <term><constant>SD_EVENT_PREPARING</constant></term>
 155
 156         <listitem><para>An event source is currently being prepared,
 157         i.e. the preparation handler is currently being executed, as
 158         set with
 159         <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This
 160         state is only seen in the event source preparation handler
 161         that is invoked from the
 162         <function>sd_event_prepare()</function> call and is
 163         immediately followed by <constant>SD_EVENT_ARMED</constant> or
 164         <constant>SD_EVENT_PENDING</constant>.</para>
 165
 166         <xi:include href="version-info.xml" xpointer="v229"/></listitem>
 167       </varlistentry>
 168
 169       <varlistentry>
 170         <term><constant>SD_EVENT_ARMED</constant></term>
 171
 172         <listitem><para><function>sd_event_prepare()</function> has
 173         been called and no event sources were ready to be
 174         dispatched. Use <function>sd_event_wait()</function> to wait
 175         for new events, and transition into
 176         <constant>SD_EVENT_PENDING</constant> or back into
 177         <constant>SD_EVENT_INITIAL</constant>.</para>
 178
 179         <xi:include href="version-info.xml" xpointer="v229"/></listitem>
 180       </varlistentry>
 181
 182       <varlistentry>
 183         <term><constant>SD_EVENT_PENDING</constant></term>
 184
 185         <listitem><para><function>sd_event_prepare()</function> or
 186         <function>sd_event_wait()</function> have been called and
 187         there were event sources with events pending. Use
 188         <function>sd_event_dispatch()</function> to dispatch the
 189         highest priority event source and transition back to
 190         <constant>SD_EVENT_INITIAL</constant>, or
 191         <constant>SD_EVENT_FINISHED</constant>.</para>
 192
 193         <xi:include href="version-info.xml" xpointer="v229"/></listitem>
 194       </varlistentry>
 195
 196       <varlistentry>
 197         <term><constant>SD_EVENT_RUNNING</constant></term>
 198
 199         <listitem><para>A regular event source is currently being
 200         dispatched. This state is only seen in the event source
 201         handler that is invoked from the
 202         <function>sd_event_dispatch()</function> call, and is
 203         immediately followed by <constant>SD_EVENT_INITIAL</constant>
 204         or <constant>SD_EVENT_FINISHED</constant> as soon the event
 205         source handler returns. Note that during dispatching of exit
 206         event sources the <constant>SD_EVENT_EXITING</constant> state
 207         is seen instead.</para>
 208
 209         <xi:include href="version-info.xml" xpointer="v229"/></listitem>
 210       </varlistentry>
 211
 212       <varlistentry>
 213         <term><constant>SD_EVENT_EXITING</constant></term>
 214
 215         <listitem><para>Similar to
 216         <constant>SD_EVENT_RUNNING</constant> but is the state in
 217         effect while dispatching exit event sources. It is followed by
 218         <constant>SD_EVENT_INITIAL</constant> or
 219         <constant>SD_EVENT_FINISHED</constant> as soon as the event
 220         handler returns.</para>
 221
 222         <xi:include href="version-info.xml" xpointer="v229"/></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>
 231
 232         <xi:include href="version-info.xml" xpointer="v229"/></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.  On failure, they return a negative
 272     errno-style error code. In case of <function>sd_event_prepare()</function> and
 273     <function>sd_event_wait()</function>, a positive, non-zero return code indicates that events are ready to
 274     be processed and zero indicates that no events are ready. In case of
 275     <function>sd_event_dispatch()</function>, a positive, non-zero return code indicates that the event loop
 276     returned to its initial state and zero indicates the event loop has
 277     exited. <function>sd_event_get_state()</function> returns a positive or zero state on success.</para>
 278
 279     <refsect2>
 280       <title>Errors</title>
 281
 282       <para>Returned errors may indicate the following problems:</para>
 283
 284       <variablelist>
 285         <varlistentry>
 286           <term><constant>-EINVAL</constant></term>
 287
 288           <listitem><para>The <parameter>event</parameter> parameter is invalid or <constant>NULL</constant>.
 289           </para></listitem>
 290         </varlistentry>
 291
 292         <varlistentry>
 293           <term><constant>-EBUSY</constant></term>
 294
 295           <listitem><para>The event loop object is not in the right state.</para></listitem>
 296         </varlistentry>
 297
 298         <varlistentry>
 299           <term><constant>-ESTALE</constant></term>
 300
 301           <listitem><para>The event loop is already terminated.</para></listitem>
 302
 303         </varlistentry>
 304
 305         <varlistentry>
 306           <term><constant>-ECHILD</constant></term>
 307
 308           <listitem><para>The event loop has been created in a different process, library or module instance.</para></listitem>
 309
 310         </varlistentry>
 311
 312       </variablelist>
 313
 314       <para>Other errors are possible, too.</para>
 315     </refsect2>
 316   </refsect1>
 317
 318   <xi:include href="libsystemd-pkgconfig.xml" />
 319
 320   <refsect1>
 321     <title>History</title>
 322     <para><function>sd_event_prepare()</function>,
 323     <function>sd_event_wait()</function>, and
 324     <function>sd_event_dispatch()</function> were added in version 220.</para>
 325     <para><function>sd_event_get_state()</function> was added in version 229.</para>
 326     <para><function>sd_event_get_iteration()</function> was added in version 231.</para>
 327   </refsect1>
 328
 329   <refsect1>
 330     <title>See Also</title>
 331
 332     <para>
 333       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 334       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 335       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 336       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 337       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 338       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 339       <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 340       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 341       <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 342       <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 343       <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 344     </para>
 345   </refsect1>
 346
 347 </refentry>