Debian Codegraph @

upstream/debian-unstable/man3/sd-event.3

raw
1 '\" t
2 .TH "SD\-EVENT" "3" "" "systemd 261~rc3" "sd-event"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd-event \- A generic event loop implementation
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-event\&.h>
29 .fi
30 .ft
31 .HP \w'\fBpkg\-config\ \-\-cflags\ \-\-libs\ libsystemd\fR\ 'u
32 \fBpkg\-config \-\-cflags \-\-libs libsystemd\fR
33 .SH "DESCRIPTION"
34 .PP
35 sd\-event\&.h
36 is part of
37 \fBlibsystemd\fR(3)
38 and provides a generic event loop implementation, based on Linux
39 \fBepoll\fR(7)\&.
40 .PP
41 See
42 \fBsd_event_new\fR(3),
43 \fBsd_event_run\fR(3),
44 \fBsd_event_add_io\fR(3),
45 \fBsd_event_add_time\fR(3),
46 \fBsd_event_add_signal\fR(3),
47 \fBsd_event_add_child\fR(3),
48 \fBsd_event_add_inotify\fR(3),
49 \fBsd_event_add_defer\fR(3),
50 \fBsd_event_add_memory_pressure\fR(3),
51 \fBsd_event_source_unref\fR(3),
52 \fBsd_event_source_set_priority\fR(3),
53 \fBsd_event_source_set_enabled\fR(3),
54 \fBsd_event_source_set_userdata\fR(3),
55 \fBsd_event_source_get_event\fR(3),
56 \fBsd_event_source_get_pending\fR(3),
57 \fBsd_event_source_set_description\fR(3),
58 \fBsd_event_source_set_prepare\fR(3),
59 \fBsd_event_source_set_ratelimit\fR(3),
60 \fBsd_event_wait\fR(3),
61 \fBsd_event_get_fd\fR(3),
62 \fBsd_event_set_watchdog\fR(3),
63 \fBsd_event_exit\fR(3),
64 \fBsd_event_now\fR(3)
65 for more information about the functions available\&.
66 .PP
67 The event loop design is targeted on running a separate instance of the event loop in each thread; it has no concept of distributing events from a single event loop instance onto multiple worker threads\&. Dispatching events is strictly ordered and subject to configurable priorities\&. In each event loop iteration a single event source is dispatched\&. Each time an event source is dispatched the kernel is polled for new events, before the next event source is dispatched\&. The event loop is designed to honor priorities and provide fairness within each priority\&. It is not designed to provide optimal throughput, as this contradicts these goals due the limitations of the underlying
68 \fBepoll\fR(7)
69 primitives\&.
70 .PP
71 The event loop implementation provides the following features:
72 .sp
73 .RS 4
74 .ie n \{\
75 \h'-04' 1.\h'+01'\c
76 .\}
77 .el \{\
78 .sp -1
79 .IP " 1." 4.2
80 .\}
81 I/O event sources, based on
82 \fBepoll\fR(7)\*(Aqs file descriptor watching, including edge triggered events (\fBEPOLLET\fR)\&. See
83 \fBsd_event_add_io\fR(3)\&.
84 .RE
85 .sp
86 .RS 4
87 .ie n \{\
88 \h'-04' 2.\h'+01'\c
89 .\}
90 .el \{\
91 .sp -1
92 .IP " 2." 4.2
93 .\}
94 Timer event sources, based on
95 \fBtimerfd_create\fR(2), supporting the
96 \fBCLOCK_MONOTONIC\fR,
97 \fBCLOCK_REALTIME\fR,
98 \fBCLOCK_BOOTTIME\fR
99 clocks, as well as the
100 \fBCLOCK_REALTIME_ALARM\fR
101 and
102 \fBCLOCK_BOOTTIME_ALARM\fR
103 clocks that can resume the system from suspend\&. When creating timer events a required accuracy parameter may be specified which allows coalescing of timer events to minimize power consumption\&. See
104 \fBsd_event_add_time\fR(3)\&.
105 .RE
106 .sp
107 .RS 4
108 .ie n \{\
109 \h'-04' 3.\h'+01'\c
110 .\}
111 .el \{\
112 .sp -1
113 .IP " 3." 4.2
114 .\}
115 UNIX process signal events, based on
116 \fBsignalfd\fR(2), including full support for real\-time signals, and queued parameters\&. See
117 \fBsd_event_add_signal\fR(3)\&.
118 .RE
119 .sp
120 .RS 4
121 .ie n \{\
122 \h'-04' 4.\h'+01'\c
123 .\}
124 .el \{\
125 .sp -1
126 .IP " 4." 4.2
127 .\}
128 Child process state change events, based on
129 \fBwaitid\fR(2)\&. See
130 \fBsd_event_add_child\fR(3)\&.
131 .RE
132 .sp
133 .RS 4
134 .ie n \{\
135 \h'-04' 5.\h'+01'\c
136 .\}
137 .el \{\
138 .sp -1
139 .IP " 5." 4.2
140 .\}
141 Static event sources, of three types: defer, post and exit, for invoking calls in each event loop, after other event sources or at event loop termination\&. See
142 \fBsd_event_add_defer\fR(3)\&.
143 .RE
144 .sp
145 .RS 4
146 .ie n \{\
147 \h'-04' 6.\h'+01'\c
148 .\}
149 .el \{\
150 .sp -1
151 .IP " 6." 4.2
152 .\}
153 Event sources may be assigned a 64\-bit priority value, that controls the order in which event sources are dispatched if multiple are pending simultaneously\&. See
154 \fBsd_event_source_set_priority\fR(3)\&.
155 .RE
156 .sp
157 .RS 4
158 .ie n \{\
159 \h'-04' 7.\h'+01'\c
160 .\}
161 .el \{\
162 .sp -1
163 .IP " 7." 4.2
164 .\}
165 The event loop may automatically send watchdog notification messages to the service manager\&. See
166 \fBsd_event_set_watchdog\fR(3)\&.
167 .RE
168 .sp
169 .RS 4
170 .ie n \{\
171 \h'-04' 8.\h'+01'\c
172 .\}
173 .el \{\
174 .sp -1
175 .IP " 8." 4.2
176 .\}
177 The event loop may be integrated into foreign event loops, such as the GLib one\&. See
178 \fBsd_event_get_fd\fR(3)
179 for an example\&.
180 .RE
181 .SH "NOTES"
182 .PP
183 Functions described here are available as a shared library, which can be compiled against and linked to with the
184 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
185 file\&.
186 .PP
187 The code described here uses
188 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
189 \fBsetenv\fR(3)
190 from a parallel thread\&. It is recommended to only do calls to
191 \fBsetenv()\fR
192 from an early phase of the program when no other threads have been started\&.
193 .SH "SEE ALSO"
194 .PP
195 \fBsystemd\fR(1), \fBsd_event_new\fR(3), \fBsd_event_run\fR(3), \fBsd_event_add_io\fR(3), \fBsd_event_add_time\fR(3), \fBsd_event_add_signal\fR(3), \fBsd_event_add_child\fR(3), \fBsd_event_add_inotify\fR(3), \fBsd_event_add_defer\fR(3), \fBsd_event_add_memory_pressure\fR(3), \fBsd_event_source_unref\fR(3), \fBsd_event_source_set_priority\fR(3), \fBsd_event_source_set_enabled\fR(3), \fBsd_event_source_set_userdata\fR(3), \fBsd_event_source_get_event\fR(3), \fBsd_event_source_get_pending\fR(3), \fBsd_event_source_set_description\fR(3), \fBsd_event_source_set_prepare\fR(3), \fBsd_event_source_set_ratelimit\fR(3), \fBsd_event_wait\fR(3), \fBsd_event_get_fd\fR(3), \fBsd_event_set_watchdog\fR(3), \fBsd_event_exit\fR(3), \fBsd_event_now\fR(3), \fBepoll\fR(7), \fBtimerfd_create\fR(2), \fBsignalfd\fR(2), \fBwaitid\fR(2)