2015-03-14 04:35:32 +03:00
<?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">
<!--
This file is part of systemd.
Copyright 2015 Zbigniew Jędrzejewski-Szmek
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http: / / w w w . g n u . o r g / l i c e n s e s /> .
-->
<refentry id= "sd_event_wait" conditional= "ENABLE_KDBUS" >
<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>
<refpurpose > Run parts of libsystemd event loop</refpurpose>
</refnamediv>
<refsynopsisdiv >
<funcsynopsis >
<funcsynopsisinfo > #include < systemd/sd-event.h> </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 > timeout</parameter> </paramdef>
</funcprototype>
<funcprototype >
<funcdef > int <function > sd_event_dispatch</function> </funcdef>
<paramdef > sd_event *<parameter > event</parameter> </paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 >
<title > Description</title>
<para > Functions described here form parts of an event loop.</para>
<para > <function > sd_event_prepare</function> checks for pending
events and arms necessary timers. If any events are ready to be
processed, it returns a positive value, and the events should be
processed with <function > sd_event_dispatch</function> .
<function > sd_event_dispatch</function> runs a handler for one of
the events from the sources with the highest priority. On success,
<function > sd_event_dispatch</function> returns either 0, which
means that the loop is finished, or a positive value, which means
that the loop is again in the initial state and
<function > sd_event_prepare</function> should be called again.
</para>
<para > In case <function > sd_event_prepare</function> returned 0,
<function > sd_event_wait</function> should be called to wait for
events or a timeout. If any events are ready to be processed, it
returns a positive value, and the events should be processed with
<function > sd_event_dispatch</function> . Otherwise, the loop is
2015-05-11 14:49:29 +03:00
back in the initial state and <function > sd_event_prepare</function>
2015-03-14 04:35:32 +03:00
should be called again.</para>
<programlisting >
┌──────────┐
│ initial ├──←←←←←←←←←←←←←←←←←←←─┐
└───┬──────┘ ↑
│ ↑
sd_event_prepare ┌─────────┐ ↑
├ 0 →→→→→→→──┤ armed │ ↑
1 └───┬─────┘ ↑
↓ │ ↑
↓ sd_event_wait ↑
├───←←←←←←←─── 1 ┴─ 0 →→→→→→→─┘
┌───┴──────┐ ↑
│ pending │ ↑
└───┬──────┘ ↑
│ ↑
sd_event_dispatch ↑
↓ ↑
├ 1 ──────────→→→→→→→─────────┘
0
↓
┌───┴──────┐
│ finished │
└──────────┘
</programlisting>
<para > All three functions as the first argument take the event
loop object <parameter > event</parameter> that is created with with
<function > sd_event_new</function> . The timeout for
<function > sd_event_wait</function> is specified with
<parameter > timeout</parameter> in milliseconds.
<constant > (uint64_t) -1</constant> may be used to specify an
infinite timeout.</para>
</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 value means that
events are ready to be processed and 0 means that no events are
ready. In case of <function > sd_event_dispatch</function> a
positive value means that the loop is again in the initial state
and 0 means the loop is finished. For any of those functions, a
negative return value means the loop must be aborted.</para>
</refsect1>
<refsect1 >
<title > Errors</title>
<para > Returned errors may indicate the following problems:</para>
<variablelist >
<varlistentry >
<term > <constant > -EINVAL</constant> </term>
<listitem > <para > Parameter <parameter > event</parameter> is
<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>
<refsect1 >
<title > Notes</title>
<para > Functions described here are available
as a shared library, which can be compiled and linked to with the
<constant > libsystemd</constant> <citerefentry project= 'die-net' > <refentrytitle > pkg-config</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry>
file.</para>
</refsect1>
<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_run</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> .
</para>
</refsect1>
</refentry>
