tree-wide: beautify remaining copyright statements

[thirdparty/systemd.git] / man / sd_event_wait.xml

<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  SPDX-License-Identifier: LGPL-2.1+

  Copyright © 2015 Zbigniew Jędrzejewski-Szmek
-->

<refentry id="sd_event_wait" xmlns:xi="http://www.w3.org/2001/XInclude">

  <refentryinfo>
    <title>sd_event_wait</title>
    <productname>systemd</productname>

    <authorgroup>
      <author>
        <contrib>Developer</contrib>
        <firstname>Tom</firstname>
        <surname>Gundersen</surname>
        <email>teg@jklm.no</email>
      </author>
    </authorgroup>
  </refentryinfo>

  <refmeta>
    <refentrytitle>sd_event_wait</refentrytitle>
    <manvolnum>3</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>sd_event_wait</refname>
    <refname>sd_event_prepare</refname>
    <refname>sd_event_dispatch</refname>
    <refname>sd_event_get_state</refname>
    <refname>sd_event_get_iteration</refname>
    <refname>SD_EVENT_INITIAL</refname>
    <refname>SD_EVENT_PREPARING</refname>
    <refname>SD_EVENT_ARMED</refname>
    <refname>SD_EVENT_PENDING</refname>
    <refname>SD_EVENT_RUNNING</refname>
    <refname>SD_EVENT_EXITING</refname>
    <refname>SD_EVENT_FINISHED</refname>

    <refpurpose>Low-level event loop operations</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>

      <funcsynopsisinfo><token>enum</token> {
        <constant>SD_EVENT_INITIAL</constant>,
        <constant>SD_EVENT_PREPARING</constant>,
        <constant>SD_EVENT_ARMED</constant>,
        <constant>SD_EVENT_PENDING</constant>,
        <constant>SD_EVENT_RUNNING</constant>,
        <constant>SD_EVENT_EXITING</constant>,
        <constant>SD_EVENT_FINISHED</constant>,
};</funcsynopsisinfo>

      <funcprototype>
        <funcdef>int <function>sd_event_prepare</function></funcdef>
        <paramdef>sd_event *<parameter>event</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>int <function>sd_event_wait</function></funcdef>
        <paramdef>sd_event *<parameter>event</parameter></paramdef>
        <paramdef>uint64_t <parameter>usec</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>int <function>sd_event_dispatch</function></funcdef>
        <paramdef>sd_event *<parameter>event</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>int <function>sd_event_get_state</function></funcdef>
        <paramdef>sd_event *<parameter>event</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>int <function>sd_event_get_iteration</function></funcdef>
        <paramdef>sd_event *<parameter>event</parameter></paramdef>
        <paramdef>uint64_t *<parameter>ret</parameter></paramdef>
      </funcprototype>

    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para>The low-level <function>sd_event_prepare()</function>,
    <function>sd_event_wait()</function> and
    <function>sd_event_dispatch()</function> functions may be used to
    execute specific phases of an event loop. See
    <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>
    and
    <citerefentry><refentrytitle>sd_event_loop</refentrytitle><manvolnum>3</manvolnum></citerefentry>
    for higher-level functions that execute individual but complete
    iterations of an event loop or run it continuously.</para>

    <para><function>sd_event_prepare()</function> checks for pending
    events and arms necessary timers. If any events are ready to be
    processed ("pending"), it returns a positive, non-zero value, and the caller
    should process these events with
    <function>sd_event_dispatch()</function>.</para>

    <para><function>sd_event_dispatch()</function> dispatches the
    highest priority event source that has a pending event. On
    success, <function>sd_event_dispatch()</function> returns either
    zero, which indicates that no further event sources may be
    dispatched and exiting of the event loop was requested via
    <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>;
    or a positive non-zero value, which means that an event source was
    dispatched and the loop returned to its initial state, and the
    caller should initiate the next event loop iteration by invoking
    <function>sd_event_prepare()</function> again.</para>

    <para>In case <function>sd_event_prepare()</function> returned
    zero, <function>sd_event_wait()</function> should be called to
    wait for further events or a timeout. If any events are ready to
    be processed, it returns a positive, non-zero value, and the
    events should be dispatched with
    <function>sd_event_dispatch()</function>. Otherwise, the event
    loop returned to its initial state and the next event loop
    iteration should be initiated by invoking
    <function>sd_event_prepare()</function> again.</para>

    <para><function>sd_event_get_state()</function> may be used to
    determine the state the event loop is currently in. It returns one
    of the states described below.</para>

    <para><function>sd_event_get_iteration()</function> may be used to determine the current iteration of the event
    loop. It returns an unsigned 64bit integer containing a counter that increases monotonically with each iteration of
    the event loop, starting with 0. The counter is increased at the time of the
    <function>sd_event_prepare()</function> invocation.</para>

    <para>All five functions take, as the first argument, the event loop object <parameter>event</parameter> that has
    been created with <function>sd_event_new()</function>. The timeout for <function>sd_event_wait()</function> is
    specified in <parameter>usec</parameter> in microseconds.  <constant>(uint64_t) -1</constant> may be used to
    specify an infinite timeout.</para>
</refsect1>

  <refsect1>
    <title>State Machine</title>

    <para>The event loop knows the following states, that may be
    queried with <function>sd_event_get_state()</function>.</para>

    <variablelist>
      <varlistentry>
        <term><constant>SD_EVENT_INITIAL</constant></term>

        <listitem><para>The initial state the event loop is in,
        before each event loop iteration. Use
        <function>sd_event_prepare()</function> to transition the
        event loop into the <constant>SD_EVENT_ARMED</constant> or
        <constant>SD_EVENT_PENDING</constant> states.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><constant>SD_EVENT_PREPARING</constant></term>

        <listitem><para>An event source is currently being prepared,
        i.e. the preparation handler is currently being executed, as
        set with
        <citerefentry><refentrytitle>sd_event_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This
        state is only seen in the event source preparation handler
        that is invoked from the
        <function>sd_event_prepare()</function> call and is
        immediately followed by <constant>SD_EVENT_ARMED</constant> or
        <constant>SD_EVENT_PENDING</constant>.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><constant>SD_EVENT_ARMED</constant></term>

        <listitem><para><function>sd_event_prepare()</function> has
        been called and no event sources were ready to be
        dispatched. Use <function>sd_event_wait()</function> to wait
        for new events, and transition into
        <constant>SD_EVENT_PENDING</constant> or back into
        <constant>SD_EVENT_INITIAL</constant>.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><constant>SD_EVENT_PENDING</constant></term>

        <listitem><para><function>sd_event_prepare()</function> or
        <function>sd_event_wait()</function> have been called and
        there were event sources with events pending. Use
        <function>sd_event_dispatch()</function> to dispatch the
        highest priority event source and transition back to
        <constant>SD_EVENT_INITIAL</constant>, or
        <constant>SD_EVENT_FINISHED</constant>.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><constant>SD_EVENT_RUNNING</constant></term>

        <listitem><para>A regular event source is currently being
        dispatched. This state is only seen in the event source
        handler that is invoked from the
        <function>sd_event_dispatch()</function> call, and is
        immediately followed by <constant>SD_EVENT_INITIAL</constant>
        or <constant>SD_EVENT_FINISHED</constant> as soon the event
        source handler returns. Note that during dispatching of exit
        event sources the <constant>SD_EVENT_EXITING</constant> state
        is seen instead.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><constant>SD_EVENT_EXITING</constant></term>

        <listitem><para>Similar to
        <constant>SD_EVENT_RUNNING</constant> but is the state in
        effect while dispatching exit event sources. It is followed by
        <constant>SD_EVENT_INITIAL</constant> or
        <constant>SD_EVENT_FINISHED</constant> as soon as the event
        handler returns.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><constant>SD_EVENT_FINISHED</constant></term>

        <listitem><para>The event loop has exited. All exit event
        sources have run. If the event loop is in this state it serves
        no purpose anymore, and should be freed.</para></listitem>
      </varlistentry>

    </variablelist>

    <para>A simplified flow chart of the states and the calls to
    transition between them is shown below. Note that
    <constant>SD_EVENT_PREPARING</constant>,
    <constant>SD_EVENT_RUNNING</constant> and
    <constant>SD_EVENT_EXITING</constant> are not shown here.</para>

    <programlisting>
          INITIAL -&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---\
             |                                                     |
             |                                                     ^
             |                                                     |
             v                 ret == 0                            |
      sd_event_prepare() &gt;---&gt;---&gt;---&gt;---&gt;- ARMED                  |
             |                                |                    ^
             | ret > 0                        |                    |
             |                                |                    |
             v                                v          ret == 0  |
          PENDING &lt;---&lt;---&lt;---&lt;---&lt;---&lt; sd_event_wait() &gt;---&gt;---&gt;--+
             |           ret > 0                                   ^
             |                                                     |
             |                                                     |
             v                                                     |
      sd_event_dispatch() &gt;---&gt;---&gt;---&gt;---&gt;---&gt;---&gt;---&gt;---&gt;---&gt;---&gt;/
             |                             ret > 0
             | ret == 0
             |
             v
          FINISHED
    </programlisting>
  </refsect1>

  <refsect1>
    <title>Return Value</title>

    <para>On success, these functions return 0 or a positive integer.
    On failure, they return a negative errno-style error code. In case
    of <function>sd_event_prepare()</function> and
    <function>sd_event_wait()</function>, a positive, non-zero return
    code indicates that events are ready to be processed and zero
    indicates that no events are ready. In case of
    <function>sd_event_dispatch()</function>, a positive, non-zero
    return code indicates that the event loop returned to its initial
    state and zero indicates the event loop has
    exited. <function>sd_event_get_state()</function> returns a
    positive or zero state on success.</para>
  </refsect1>

  <refsect1>
    <title>Errors</title>

    <para>Returned errors may indicate the following problems:</para>

    <variablelist>
      <varlistentry>
        <term><constant>-EINVAL</constant></term>

        <listitem><para>The <parameter>event</parameter> parameter is
        invalid or <constant>NULL</constant>.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><constant>-EBUSY</constant></term>

        <listitem><para>The event loop object is not in the right
        state.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><constant>-ESTALE</constant></term>

        <listitem><para>The event loop is already terminated.</para></listitem>

      </varlistentry>

      <varlistentry>
        <term><constant>-ECHILD</constant></term>

        <listitem><para>The event loop has been created in a different process.</para></listitem>

      </varlistentry>

    </variablelist>

    <para>Other errors are possible, too.</para>
  </refsect1>

  <xi:include href="libsystemd-pkgconfig.xml" />

  <refsect1>
    <title>See Also</title>

    <para>
      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>
    </para>
  </refsect1>

</refentry>