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