mirror of
https://github.com/systemd/systemd.git
synced 2024-11-23 18:23:32 +08:00
fe45f8dc9b
In the troff output, this doesn't seem to make any difference. But in the html output, the whitespace is sometimes preserved, creating an additional gap before the following content. Drop it everywhere to avoid this.
348 lines
15 KiB
XML
348 lines
15 KiB
XML
<?xml version='1.0'?>
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
|
|
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
|
|
|
|
<refentry id="sd_event_wait" xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
|
|
<refentryinfo>
|
|
<title>sd_event_wait</title>
|
|
<productname>systemd</productname>
|
|
</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 <systemd/sd-event.h></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 64-bit 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>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v229"/></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_source_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>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v229"/></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>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v229"/></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>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v229"/></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>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v229"/></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>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v229"/></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>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v229"/></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 -<---<---<---<---<---<---<---<---<---<---<---<---\
|
|
| |
|
|
| ^
|
|
| |
|
|
v ret == 0 |
|
|
sd_event_prepare() >--->--->--->--->- ARMED |
|
|
| | ^
|
|
| ret > 0 | |
|
|
| | |
|
|
v v ret == 0 |
|
|
PENDING <---<---<---<---<---< sd_event_wait() >--->--->--+
|
|
| ret > 0 ^
|
|
| |
|
|
| |
|
|
v |
|
|
sd_event_dispatch() >--->--->--->--->--->--->--->--->--->--->/
|
|
| 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>
|
|
|
|
<refsect2>
|
|
<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, library or module instance.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
<para>Other errors are possible, too.</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<xi:include href="libsystemd-pkgconfig.xml" />
|
|
|
|
<refsect1>
|
|
<title>History</title>
|
|
<para><function>sd_event_prepare()</function>,
|
|
<function>sd_event_wait()</function>,
|
|
<function>sd_event_dispatch()</function>, and
|
|
<function>sd_event_get_state()</function> were added in version 221.</para>
|
|
<para><function>sd_event_get_iteration()</function> was added in version 231.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<para><simplelist type="inline">
|
|
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
|
|
</simplelist></para>
|
|
</refsect1>
|
|
|
|
</refentry>
|