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">
6 SPDX-License-Identifier: LGPL-2.1+
9 <refentry id="sd_event_new" xmlns:xi="http://www.w3.org/2001/XInclude">
12 <title>sd_event_new</title>
13 <productname>systemd</productname>
17 <contrib>Developer</contrib>
18 <firstname>Lennart</firstname>
19 <surname>Poettering</surname>
20 <email>lennart@poettering.net</email>
26 <refentrytitle>sd_event_new</refentrytitle>
27 <manvolnum>3</manvolnum>
31 <refname>sd_event_new</refname>
32 <refname>sd_event_default</refname>
33 <refname>sd_event_ref</refname>
34 <refname>sd_event_unref</refname>
35 <refname>sd_event_unrefp</refname>
36 <refname>sd_event_get_tid</refname>
37 <refname>sd_event</refname>
39 <refpurpose>Acquire and release an event loop object</refpurpose>
44 <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo>
46 <funcsynopsisinfo><token>typedef</token> struct sd_event sd_event;</funcsynopsisinfo>
49 <funcdef>int <function>sd_event_new</function></funcdef>
50 <paramdef>sd_event **<parameter>event</parameter></paramdef>
54 <funcdef>int <function>sd_event_default</function></funcdef>
55 <paramdef>sd_event **<parameter>event</parameter></paramdef>
59 <funcdef>sd_event *<function>sd_event_ref</function></funcdef>
60 <paramdef>sd_event *<parameter>event</parameter></paramdef>
64 <funcdef>sd_event *<function>sd_event_unref</function></funcdef>
65 <paramdef>sd_event *<parameter>event</parameter></paramdef>
69 <funcdef>void <function>sd_event_unrefp</function></funcdef>
70 <paramdef>sd_event **<parameter>event</parameter></paramdef>
74 <funcdef>int <function>sd_event_get_tid</function></funcdef>
75 <paramdef>sd_event *<parameter>event</parameter></paramdef>
76 <paramdef>pid_t *<parameter>tid</parameter></paramdef>
83 <title>Description</title>
85 <para><function>sd_event_new()</function> allocates a new event
86 loop object. The event loop object is returned in the
87 <parameter>event</parameter> parameter. After use, drop
88 the returned reference with
89 <function>sd_event_unref()</function>. When the last reference is
90 dropped, the object is freed.</para>
92 <para><function>sd_event_default()</function> acquires a reference
93 to the default event loop object of the calling thread, possibly
94 allocating a new object if no default event loop object has been
95 allocated yet for the thread. After use, drop the returned
96 reference with <function>sd_event_unref()</function>. When the
97 last reference is dropped, the event loop is freed. If this
98 function is called while the object returned from a previous call
99 from the same thread is still referenced, the same object is
100 returned again, but the reference is increased by one. It is
101 recommended to use this call instead of
102 <function>sd_event_new()</function> in order to share event loop
103 objects between various components that are dispatched in the same
104 thread. All threads have exactly either zero or one default event loop
105 objects associated, but never more.</para>
107 <para>After allocating an event loop object, add event sources to
109 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
110 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
111 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
112 <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>
114 <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
115 and then execute the event loop using
116 <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
118 <para><function>sd_event_ref()</function> increases the reference
119 count of the specified event loop object by one.</para>
121 <para><function>sd_event_unref()</function> decreases the
122 reference count of the specified event loop object by one. If
123 the count hits zero, the object is freed. Note that it
124 is freed regardless of whether it is the default event loop object for a
125 thread or not. This means that allocating an event loop with
126 <function>sd_event_default()</function>, then releasing it, and
127 then acquiring a new one with
128 <function>sd_event_default()</function> will result in two
129 distinct objects. Note that, in order to free an event loop object,
130 all remaining event sources of the event loop also need to be
131 freed as each keeps a reference to it.</para>
133 <para><function>sd_event_unrefp()</function> is similar to
134 <function>sd_event_unref()</function> but takes a pointer to a
135 pointer to an <type>sd_event</type> object. This call is useful in
136 conjunction with GCC's and LLVM's <ulink
137 url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
138 Variable Attribute</ulink>. Note that this function is defined as
139 inline function. Use a declaration like the following,
140 in order to allocate an event loop object that is freed
141 automatically as the code block is left:</para>
144 __attribute__((cleanup(sd_event_unrefp)) sd_event *event = NULL;
147 r = sd_event_default(&event);
149 fprintf(stderr, "Failed to allocate event loop: %s\n", strerror(-r));
153 <para><function>sd_event_ref()</function>,
154 <function>sd_event_unref()</function> and
155 <function>sd_event_unrefp()</function> execute no operation if the
156 passed in event loop object is <constant>NULL</constant>.</para>
158 <para><function>sd_event_get_tid()</function> retrieves the thread
159 identifier ("TID") of the thread the specified event loop object
160 is associated with. This call is only supported for event loops
161 allocated with <function>sd_event_default()</function>, and
162 returns the identifier for the thread the event loop is the
163 default event loop of. See <citerefentry
164 project='man-pages'><refentrytitle>gettid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
165 for more information on thread identifiers.</para>
169 <title>Return Value</title>
171 <para>On success, <function>sd_event_new()</function>,
172 <function>sd_event_default()</function> and
173 <function>sd_event_get_tid()</function> return 0 or a positive
174 integer. On failure, they return a negative errno-style error
175 code. <function>sd_event_ref()</function> always returns a pointer
176 to the event loop object passed
177 in. <function>sd_event_unref()</function> always returns
178 <constant>NULL</constant>.</para>
182 <title>Errors</title>
184 <para>Returned errors may indicate the following problems:</para>
188 <term><constant>-ENOMEM</constant></term>
190 <listitem><para>Not enough memory to allocate the object.</para></listitem>
194 <term><constant>-EMFILE</constant></term>
196 <listitem><para>The maximum number of event loops has been allocated.</para></listitem>
201 <term><constant>-ENXIO</constant></term>
203 <listitem><para><function>sd_event_get_tid()</function> was
204 invoked on an event loop object that was not allocated with
205 <function>sd_event_default()</function>.</para></listitem>
211 <xi:include href="libelogind-pkgconfig.xml" />
214 <title>See Also</title>
217 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
218 <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
219 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
220 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
221 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
222 <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
223 <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
224 <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
225 <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
226 <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
227 <citerefentry project='man-pages'><refentrytitle>gettid</refentrytitle><manvolnum>2</manvolnum></citerefentry>