chiark / gitweb /
pid1: preserve current value of log target across re-{load,execution}
[elogind.git] / man / sd-event.xml
1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5 <!--
6   This file is part of elogind.
7   SPDX-License-Identifier: LGPL-2.1+
8
9
10   Copyright 2015 Lennart Poettering
11 -->
12
13 <refentry id="sd-event" xmlns:xi="http://www.w3.org/2001/XInclude">
14
15   <refentryinfo>
16     <title>sd-event</title>
17     <productname>elogind</productname>
18
19     <authorgroup>
20       <author>
21         <contrib>Developer</contrib>
22         <firstname>Lennart</firstname>
23         <surname>Poettering</surname>
24         <email>lennart@poettering.net</email>
25       </author>
26     </authorgroup>
27   </refentryinfo>
28
29   <refmeta>
30     <refentrytitle>sd-event</refentrytitle>
31     <manvolnum>3</manvolnum>
32   </refmeta>
33
34   <refnamediv>
35     <refname>sd-event</refname>
36     <refpurpose>A generic event loop implementation</refpurpose>
37   </refnamediv>
38
39   <refsynopsisdiv>
40     <funcsynopsis>
41       <funcsynopsisinfo>#include &lt;elogind/sd-event.h&gt;</funcsynopsisinfo>
42     </funcsynopsis>
43
44     <cmdsynopsis>
45       <command>pkg-config --cflags --libs libelogind</command>
46     </cmdsynopsis>
47
48   </refsynopsisdiv>
49
50   <refsect1>
51     <title>Description</title>
52
53     <para><filename>sd-event.h</filename> provides a generic event
54     loop implementation, based on Linux <citerefentry
55     project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
56     </para>
57
58     <para>See
59     <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
60     <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
61     <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
62     <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
63     <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
64     <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
65     <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
66     <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
67     <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
68     <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
69     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
70     <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
71     <citerefentry><refentrytitle>sd_event_source_get_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
72     <citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
73     <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
74     <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
75     <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
76     <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
77     <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
78     <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
79     <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>
80     for more information about the functions available.</para>
81
82     <para>The event loop design is targeted on running a separate
83     instance of the event loop in each thread; it has no concept of
84     distributing events from a single event loop instance onto
85     multiple worker threads. Dispatching events is strictly ordered
86     and subject to configurable priorities. In each event loop
87     iteration a single event source is dispatched. Each time an event
88     source is dispatched the kernel is polled for new events, before
89     the next event source is dispatched. The event loop is designed to
90     honor priorities and provide fairness within each priority. It is
91     not designed to provide optimal throughput, as this contradicts
92     these goals due the limitations of the underlying <citerefentry
93     project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>
94     primitives.</para>
95
96     <para>The event loop implementation provides the following features:</para>
97
98     <orderedlist>
99       <listitem><para>I/O event sources, based on <citerefentry
100       project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>'s
101       file descriptor watching, including edge triggered events (<constant>EPOLLET</constant>). See <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
102
103       <listitem><para>Timer event sources, based on <citerefentry
104       project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
105       supporting the <constant>CLOCK_MONOTONIC</constant>,
106       <constant>CLOCK_REALTIME</constant>,
107       <constant>CLOCK_BOOTIME</constant> clocks, as well as the
108       <constant>CLOCK_REALTIME_ALARM</constant> and
109       <constant>CLOCK_BOOTTIME_ALARM</constant> clocks that can resume
110       the system from suspend. When creating timer events a required
111       accuracy parameter may be specified which allows coalescing of
112       timer events to minimize power consumption. See <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
113
114       <listitem><para>UNIX process signal events, based on
115       <citerefentry
116       project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
117       including full support for real-time signals, and queued parameters. See <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
118
119       <listitem><para>Child process state change events, based on
120       <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>
121
122       <listitem><para>Static event sources, of three types: defer,
123       post and exit, for invoking calls in each event loop, after
124       other event sources or at event loop termination. See
125       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
126
127       <listitem><para>Event sources may be assigned a 64bit priority
128       value, that controls the order in which event sources are
129       dispatched if multiple are pending simultaneously. See
130       <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
131
132       <listitem><para>The event loop may automatically send watchdog
133       notification messages to the service manager. See
134       <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
135
136       <listitem><para>The event loop may be integrated into foreign
137       event loops, such as the GLib one. See
138       <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>
139       for an example.</para></listitem>
140     </orderedlist>
141
142   </refsect1>
143
144   <xi:include href="libelogind-pkgconfig.xml" />
145
146   <refsect1>
147     <title>See Also</title>
148     <para>
149       <!-- 0 /// elogind is in section 8
150       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
151       <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
152       --><!-- else -->
153       <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
154       <!-- // 0 -->
155       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
156       <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
157       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
158       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
159       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
160       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
161       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
162       <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
163       <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
164       <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
165       <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
166       <citerefentry><refentrytitle>sd_event_source_get_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
167       <citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
168       <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
169       <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
170       <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
171       <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
172       <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
173       <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
174       <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
175       <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
176       <citerefentry project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
177       <citerefentry project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
178       <citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
179     </para>
180   </refsect1>
181
182 </refentry>