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