dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering This file is part of systemd.
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering Copyright 2015 Lennart Poettering
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering systemd is free software; you can redistribute it and/or modify it
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering under the terms of the GNU Lesser General Public License as published by
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering the Free Software Foundation; either version 2.1 of the License, or
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering (at your option) any later version.
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering systemd is distributed in the hope that it will be useful, but
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering Lesser General Public License for more details.
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering You should have received a copy of the GNU Lesser General Public License
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering<refentry id="sd-event" xmlns:xi="http://www.w3.org/2001/XInclude">
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <refentryinfo>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </authorgroup>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </refentryinfo>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <refpurpose>A generic event loop implementation</refpurpose>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <refsynopsisdiv>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <funcsynopsis>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </funcsynopsis>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <command>pkg-config --cflags --libs libsystemd</command>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </cmdsynopsis>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </refsynopsisdiv>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para><filename>sd-event.h</filename> provides a generic event
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering loop implementation, based on Linux <citerefentry
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_get_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering for more information about the functions available.</para>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para>The event loop design is targeted on running a separate
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering instance of the event loop in each thread; it has no concept of
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering distributing events from a single event loop instance onto
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering multiple worker threads. Dispatching events is strictly ordered
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering and subject to configurable priorities. In each event loop
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering iteration a single event source is dispatched. Each time an event
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering source is dispatched the kernel is polled for new events, before
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering the next event source is dispatched. The event loop is designed to
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering honour priorities and provide fairness within each priority. It is
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering not designed to provide optimal throughput, as this contradicts
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering these goals due the limitations of the underlying <citerefentry
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering primitives.</para>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para>The event loop implementation provides the following features:</para>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <listitem><para>I/O event sources, based on <citerefentry
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>'s
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering file descriptor watching, including edge triggered events (<constant>EPOLLET</constant>). See <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <listitem><para>Timer event sources, based on <citerefentry
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering supporting the <constant>CLOCK_MONOTONIC</constant>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <constant>CLOCK_BOOTIME</constant> clocks, as well as the
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <constant>CLOCK_REALTIME_ALARM</constant> and
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <constant>CLOCK_BOOTTIME_ALARM</constant> clocks that can resume
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering the system from suspend. When creating timer events a required
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering accuracy parameter may be specified which allows coalescing of
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering timer events to minimize power consumption. See <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <listitem><para>UNIX process signal events, based on
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering including full support for real-time signals, and queued parameters. See <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <listitem><para>Child process state change events, based on
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <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>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <listitem><para>Static event sources, of three types: defer,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering post and exit, for invoking calls in each event loop, after
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering other event sources or at event loop termination. See
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <listitem><para>Event sources may be assigned a 64bit priority
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering value, that controls the order in which event sources are
7f3fdb7f19a109fa3d1be92926bfe4cea1817da5Jakub Wilk dispatched if multiple are pending simultaneously. See
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <listitem><para>The event loop may automatically send watchdog
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering notification messages to the service manager. See
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <listitem><para>The event loop may be integrated into foreign
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering event loops, such as the GLib one. See
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </orderedlist>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <xi:include href="libsystemd-pkgconfig.xml" />
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_get_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>