2N/A<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->

2N/A<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

2N/A "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

2N/A

3739N/A

2N/A<refentry id="sd-event" xmlns:xi="http://www.w3.org/2001/XInclude">

2N/A

2N/A <refentryinfo>

2N/A <title>sd-event</title>

2N/A <productname>systemd</productname>

2N/A

2N/A <authorgroup>

2N/A <author>

2N/A <contrib>Developer</contrib>

2N/A <firstname>Lennart</firstname>

59N/A <surname>Poettering</surname>

59N/A <email>lennart@poettering.net</email>

2N/A </author>

2N/A </authorgroup>

2N/A </refentryinfo>

2N/A

26N/A <refmeta>

26N/A <refentrytitle>sd-event</refentrytitle>

2N/A <manvolnum>3</manvolnum>

26N/A </refmeta>

1470N/A

38N/A <refnamediv>

1470N/A <refname>sd-event</refname>

1470N/A <refpurpose>A generic event loop implementation</refpurpose>

1470N/A </refnamediv>

181N/A

26N/A <refsynopsisdiv>

3739N/A <funcsynopsis>

3739N/A <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>

3739N/A </funcsynopsis>

3739N/A

3739N/A <cmdsynopsis>

3739N/A <command>pkg-config --cflags --libs libsystemd</command>

3739N/A </cmdsynopsis>

3739N/A

26N/A </refsynopsisdiv>

26N/A

26N/A <refsect1>

26N/A <title>Description</title>

26N/A

26N/A <para><filename>sd-event.h</filename> provides a generic event

26N/A loop implementation, based on Linux <citerefentry

700N/A project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>.

700N/A </para>

26N/A

26N/A <para>See

26N/A <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

1498N/A <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

1498N/A <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

26N/A <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

1498N/A <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

151N/A <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

206N/A <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

26N/A <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

26N/A <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

26N/A <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

26N/A <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

26N/A <citerefentry><refentrytitle>sd_event_source_get_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

2790N/A <citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

2818N/A <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

2830N/A <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

3127N/A <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

26N/A <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

3294N/A <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

26N/A <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

2N/A <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>

26N/A for more information about the functions available.</para>

26N/A

26N/A <para>The event loop design is targeted on running a separate

26N/A instance of the event loop in each thread; it has no concept of

883N/A distributing events from a single event loop instance onto

26N/A multiple worker threads. Dispatching events is strictly ordered

26N/A and subject to configurable priorities. In each event loop

26N/A iteration a single event source is dispatched. Each time an event

26N/A source is dispatched the kernel is polled for new events, before

1043N/A the next event source is dispatched. The event loop is designed to

586N/A honour priorities and provide fairness within each priority. It is

26N/A not designed to provide optimal throughput, as this contradicts

93N/A these goals due the limitations of the underlying <citerefentry

166N/A project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>

26N/A primitives.</para>

379N/A

379N/A <para>The event loop implementation provides the following features:</para>

1498N/A

1498N/A <orderedlist>

2899N/A <listitem><para>I/O event sources, based on <citerefentry

2899N/A project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>'s

2899N/A file descriptor watching, including edge triggered events (<constant>EPOLLET</constant>). See <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>

2899N/A

2899N/A <listitem><para>Timer event sources, based on <citerefentry

2899N/A project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,

2236N/A supporting the <constant>CLOCK_MONOTONIC</constant>,

2236N/A <constant>CLOCK_REALTIME</constant>,

2818N/A <constant>CLOCK_BOOTIME</constant> clocks, as well as the

2N/A <constant>CLOCK_REALTIME_ALARM</constant> and

26N/A <constant>CLOCK_BOOTTIME_ALARM</constant> clocks that can resume

26N/A the system from suspend. When creating timer events a required

181N/A accuracy parameter may be specified which allows coalescing of

181N/A timer events to minimize power consumption. See <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>

181N/A

99N/A <listitem><para>UNIX process signal events, based on

59N/A <citerefentry

12N/A project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>,

30N/A including full support for real-time signals, and queued parameters. See <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>

1256N/A

1256N/A <listitem><para>Child process state change events, based on

1256N/A <citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>. See <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>

2818N/A

1256N/A <listitem><para>Static event sources, of three types: defer,

1256N/A post and exit, for invoking calls in each event loop, after

1256N/A other event sources or at event loop termination. See

1256N/A <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>

1256N/A

1256N/A <listitem><para>Event sources may be assigned a 64bit priority

1256N/A value, that controls the order in which event sources are

1256N/A dispatched if multiple are pending simultanously. See

1256N/A <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>

2818N/A

1256N/A <listitem><para>The event loop may automatically send watchdog

1256N/A notification messages to the service manager. See

1256N/A <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>

1256N/A

1256N/A <listitem><para>The event loop may be integrated into foreign

1256N/A event loops, such as the GLib one. See

1256N/A <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>

3109N/A for an example.</para></listitem>

3109N/A </orderedlist>

3109N/A

3109N/A </refsect1>

3109N/A

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

3109N/A

3109N/A <refsect1>

3109N/A <title>See Also</title>

3109N/A <para>

3109N/A <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

3109N/A <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

3109N/A <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

3109N/A <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

3109N/A <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

3109N/A <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

3109N/A <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

1256N/A <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

1256N/A <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

1256N/A <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

3109N/A <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

3109N/A <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

1256N/A <citerefentry><refentrytitle>sd_event_source_get_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

26N/A <citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

26N/A <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

1256N/A <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

2N/A <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

26N/A <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

1256N/A <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

1256N/A <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

185N/A <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

2N/A <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>,

255N/A <citerefentry project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,

145N/A <citerefentry project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>,

7N/A <citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>

26N/A </para>

26N/A </refsect1>

38N/A

26N/A</refentry>

197N/A