along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
-<refentry id="sd_event_new" conditional="ENABLE_KDBUS">
+<refentry id="sd_event_new" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_new</title>
<refname>sd_event_default</refname>
<refname>sd_event_ref</refname>
<refname>sd_event_unref</refname>
+ <refname>sd_event_unrefp</refname>
+ <refname>sd_event_get_tid</refname>
+ <refname>sd_event</refname>
<refpurpose>Acquire and release an event loop object</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
- <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
+ <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo>
+
+ <funcsynopsisinfo><token>typedef</token> struct sd_event sd_event;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_event_new</function></funcdef>
- <paramdef>sd_
bus **<parameter>event</parameter></paramdef>
+ <paramdef>sd_
event **<parameter>event</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_default</function></funcdef>
- <paramdef>sd_
bus **<parameter>event</parameter></paramdef>
+ <paramdef>sd_
event **<parameter>event</parameter></paramdef>
</funcprototype>
<funcprototype>
- <funcdef>sd_bus *<function>sd_event_ref</function></funcdef>
- <paramdef>sd_
bus *<parameter>event</parameter></paramdef>
+ <funcdef>sd_event *<function>sd_event_ref</function></funcdef>
+ <paramdef>sd_
event *<parameter>event</parameter></paramdef>
</funcprototype>
<funcprototype>
- <funcdef>sd_bus *<function>sd_event_unref</function></funcdef>
- <paramdef>sd_bus *<parameter>event</parameter></paramdef>
+ <funcdef>sd_event *<function>sd_event_unref</function></funcdef>
+ <paramdef>sd_event *<parameter>event</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>void <function>sd_event_unrefp</function></funcdef>
+ <paramdef>sd_event **<parameter>event</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_event_get_tid</function></funcdef>
+ <paramdef>sd_event *<parameter>event</parameter></paramdef>
+ <paramdef>pid_t *<parameter>tid</parameter></paramdef>
</funcprototype>
</funcsynopsis>
thread. All threads have exactly either zero or one default event loop
objects associated, but never more.</para>
+ <para>After allocating an event loop object, add event sources to
+ it with
+ <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ or
+ <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ and then execute the event loop using
+ <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+
<para><function>sd_event_ref()</function> increases the reference
count of the specified event loop object by one.</para>
<function>sd_event_default()</function>, then releasing it, and
then acquiring a new one with
<function>sd_event_default()</function> will result in two
- distinct objects. Note that in order to free an event loop object,
+ distinct objects. Note that, in order to free an event loop object,
all remaining event sources of the event loop also need to be
freed as each keeps a reference to it.</para>
+
+ <para><function>sd_event_unrefp()</function> is similar to
+ <function>sd_event_unref()</function> but takes a pointer to a
+ pointer to an <type>sd_event</type> object. This call is useful in
+ conjunction with GCC's and LLVM's <ulink
+ url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
+ Variable Attribute</ulink>. Note that this function is defined as
+ inline function. Use a declaration like the following,
+ in order to allocate an event loop object that is freed
+ automatically as the code block is left:</para>
+
+ <programlisting>{
+ __attribute__((cleanup(sd_event_unrefp)) sd_event *event = NULL;
+ int r;
+ …
+ r = sd_event_default(&event);
+ if (r < 0)
+ fprintf(stderr, "Failed to allocate event loop: %s\n", strerror(-r));
+ …
+}</programlisting>
+
+ <para><function>sd_event_ref()</function>,
+ <function>sd_event_unref()</function> and
+ <function>sd_event_unrefp()</function> execute no operation if the
+ passed in event loop object is <constant>NULL</constant>.</para>
+
+ <para><function>sd_event_get_tid()</function> retrieves the thread
+ identifier ("TID") of the thread the specified event loop object
+ is associated with. This call is only supported for event loops
+ allocated with <function>sd_event_default()</function>, and
+ returns the identifier for the thread the event loop is the
+ default event loop of. See <citerefentry
+ project='man-pages'><refentrytitle>gettid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ for more information on thread identifiers.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
- <para>On success, <function>sd_event_new()</function> and
- <function>sd_event_default()</function> return 0 or a positive
+ <para>On success, <function>sd_event_new()</function>,
+ <function>sd_event_default()</function> and
+ <function>sd_event_get_tid()</function> return 0 or a positive
integer. On failure, they return a negative errno-style error
code. <function>sd_event_ref()</function> always returns a pointer
to the event loop object passed
<listitem><para>The maximum number of event loops has been allocated.</para></listitem>
</varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>Notes</title>
+ <varlistentry>
+ <term><constant>-ENXIO</constant></term>
- <para><function>sd_event_new()</function> and the other functions
- described here are available as a shared library, which can be
- compiled and linked to with the
- <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- file.</para>
+ <listitem><para><function>sd_event_get_tid()</function> was
+ invoked on an event loop object that was not allocated with
+ <function>sd_event_default()</function>.</para></listitem>
+ </varlistentry>
+
+ </variablelist>
</refsect1>
+ <xi:include href="libelogind-pkgconfig.xml" />
+
<refsect1>
<title>See Also</title>
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry project='man-pages'><refentrytitle>gettid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
</para>
</refsect1>
~ianmdlvl / elogind.git / blobdiff