man/sd_event_new.xml

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