man/sd_event_new.xml

   1 <?xml version='1.0'?>
   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   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="sd_event_new" xmlns:xi="http://www.w3.org/2001/XInclude">
  10
  11   <refentryinfo>
  12     <title>sd_event_new</title>
  13     <productname>systemd</productname>
  14   </refentryinfo>
  15
  16   <refmeta>
  17     <refentrytitle>sd_event_new</refentrytitle>
  18     <manvolnum>3</manvolnum>
  19   </refmeta>
  20
  21   <refnamediv>
  22     <refname>sd_event_new</refname>
  23     <refname>sd_event_default</refname>
  24     <refname>sd_event_ref</refname>
  25     <refname>sd_event_unref</refname>
  26     <refname>sd_event_unrefp</refname>
  27     <refname>sd_event_get_tid</refname>
  28     <refname>sd_event</refname>
  29
  30     <refpurpose>Acquire and release an event loop object</refpurpose>
  31   </refnamediv>
  32
  33   <refsynopsisdiv>
  34     <funcsynopsis>
  35       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  36
  37       <funcsynopsisinfo><token>typedef</token> struct sd_event sd_event;</funcsynopsisinfo>
  38
  39       <funcprototype>
  40         <funcdef>int <function>sd_event_new</function></funcdef>
  41         <paramdef>sd_event **<parameter>event</parameter></paramdef>
  42       </funcprototype>
  43
  44       <funcprototype>
  45         <funcdef>int <function>sd_event_default</function></funcdef>
  46         <paramdef>sd_event **<parameter>event</parameter></paramdef>
  47       </funcprototype>
  48
  49       <funcprototype>
  50         <funcdef>sd_event *<function>sd_event_ref</function></funcdef>
  51         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  52       </funcprototype>
  53
  54       <funcprototype>
  55         <funcdef>sd_event *<function>sd_event_unref</function></funcdef>
  56         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  57       </funcprototype>
  58
  59       <funcprototype>
  60         <funcdef>void <function>sd_event_unrefp</function></funcdef>
  61         <paramdef>sd_event **<parameter>event</parameter></paramdef>
  62       </funcprototype>
  63
  64       <funcprototype>
  65         <funcdef>int <function>sd_event_get_tid</function></funcdef>
  66         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  67         <paramdef>pid_t *<parameter>tid</parameter></paramdef>
  68       </funcprototype>
  69
  70     </funcsynopsis>
  71   </refsynopsisdiv>
  72
  73   <refsect1>
  74     <title>Description</title>
  75
  76     <para><function>sd_event_new()</function> allocates a new event
  77     loop object. The event loop object is returned in the
  78     <parameter>event</parameter> parameter. After use, drop
  79     the returned reference with
  80     <function>sd_event_unref()</function>. When the last reference is
  81     dropped, the object is freed.</para>
  82
  83     <para><function>sd_event_default()</function> acquires a reference
  84     to the default event loop object of the calling thread, possibly
  85     allocating a new object if no default event loop object has been
  86     allocated yet for the thread. After use, drop the returned
  87     reference with <function>sd_event_unref()</function>. When the
  88     last reference is dropped, the event loop is freed. If this
  89     function is called while the object returned from a previous call
  90     from the same thread is still referenced, the same object is
  91     returned again, but the reference is increased by one. It is
  92     recommended to use this call instead of
  93     <function>sd_event_new()</function> in order to share event loop
  94     objects between various components that are dispatched in the same
  95     thread. All threads have exactly either zero or one default event loop
  96     objects associated, but never more.</para>
  97
  98     <para>After allocating an event loop object, add event sources to
  99     it with
 100     <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 101     <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 102     <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 103     <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 104     or
 105     <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 106     and then execute the event loop using
 107     <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 108
 109     <para><function>sd_event_ref()</function> increases the reference
 110     count of the specified event loop object by one.</para>
 111
 112     <para><function>sd_event_unref()</function> decreases the
 113     reference count of the specified event loop object by one. If
 114     the count hits zero, the object is freed. Note that it
 115     is freed regardless of whether it is the default event loop object for a
 116     thread or not. This means that allocating an event loop with
 117     <function>sd_event_default()</function>, then releasing it, and
 118     then acquiring a new one with
 119     <function>sd_event_default()</function> will result in two
 120     distinct objects. Note that, in order to free an event loop object,
 121     all remaining event sources of the event loop also need to be
 122     freed as each keeps a reference to it.</para>
 123
 124     <para><function>sd_event_unrefp()</function> is similar to
 125     <function>sd_event_unref()</function> but takes a pointer to a
 126     pointer to an <type>sd_event</type> object. This call is useful in
 127     conjunction with GCC's and LLVM's <ulink
 128     url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
 129     Variable Attribute</ulink>. Note that this function is defined as
 130     inline function. Use a declaration like the following,
 131     in order to allocate an event loop object that is freed
 132     automatically as the code block is left:</para>
 133
 134     <programlisting>{
 135         __attribute__((cleanup(sd_event_unrefp)) sd_event *event = NULL;
 136         int r;
 137         …
 138         r = sd_event_default(&amp;event);
 139         if (r &lt; 0)
 140                 fprintf(stderr, "Failed to allocate event loop: %s\n", strerror(-r));
 141         …
 142 }</programlisting>
 143
 144     <para><function>sd_event_ref()</function>,
 145     <function>sd_event_unref()</function> and
 146     <function>sd_event_unrefp()</function> execute no operation if the
 147     passed in event loop object is <constant>NULL</constant>.</para>
 148
 149     <para><function>sd_event_get_tid()</function> retrieves the thread
 150     identifier ("TID") of the thread the specified event loop object
 151     is associated with. This call is only supported for event loops
 152     allocated with <function>sd_event_default()</function>, and
 153     returns the identifier for the thread the event loop is the
 154     default event loop of. See <citerefentry
 155     project='man-pages'><refentrytitle>gettid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 156     for more information on thread identifiers.</para>
 157   </refsect1>
 158
 159   <refsect1>
 160     <title>Return Value</title>
 161
 162     <para>On success, <function>sd_event_new()</function>,
 163     <function>sd_event_default()</function> and
 164     <function>sd_event_get_tid()</function> return 0 or a positive
 165     integer. On failure, they return a negative errno-style error
 166     code. <function>sd_event_ref()</function> always returns a pointer
 167     to the event loop object passed
 168     in. <function>sd_event_unref()</function> always returns
 169     <constant>NULL</constant>.</para>
 170   </refsect1>
 171
 172   <refsect1>
 173     <title>Errors</title>
 174
 175     <para>Returned errors may indicate the following problems:</para>
 176
 177     <variablelist>
 178       <varlistentry>
 179         <term><constant>-ENOMEM</constant></term>
 180
 181         <listitem><para>Not enough memory to allocate the object.</para></listitem>
 182       </varlistentry>
 183
 184       <varlistentry>
 185         <term><constant>-EMFILE</constant></term>
 186
 187         <listitem><para>The maximum number of event loops has been allocated.</para></listitem>
 188
 189       </varlistentry>
 190
 191       <varlistentry>
 192         <term><constant>-ENXIO</constant></term>
 193
 194         <listitem><para><function>sd_event_get_tid()</function> was
 195         invoked on an event loop object that was not allocated with
 196         <function>sd_event_default()</function>.</para></listitem>
 197       </varlistentry>
 198
 199     </variablelist>
 200   </refsect1>
 201
 202   <xi:include href="libsystemd-pkgconfig.xml" />
 203
 204   <refsect1>
 205     <title>See Also</title>
 206
 207     <para>
 208       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 209       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 210       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 211       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 212       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 213       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 214       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 215       <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 216       <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 217       <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 218       <citerefentry project='man-pages'><refentrytitle>gettid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 219     </para>
 220   </refsect1>
 221
 222 </refentry>