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+ -->
   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                 fprintf(stderr, "Failed to allocate event loop: %s\n", strerror(-r));
 140         …
 141 }</programlisting>
 142
 143     <para><function>sd_event_ref()</function>,
 144     <function>sd_event_unref()</function> and
 145     <function>sd_event_unrefp()</function> execute no operation if the
 146     passed in event loop object is <constant>NULL</constant>.</para>
 147
 148     <para><function>sd_event_get_tid()</function> retrieves the thread
 149     identifier ("TID") of the thread the specified event loop object
 150     is associated with. This call is only supported for event loops
 151     allocated with <function>sd_event_default()</function>, and
 152     returns the identifier for the thread the event loop is the
 153     default event loop of. See <citerefentry
 154     project='man-pages'><refentrytitle>gettid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 155     for more information on thread identifiers.</para>
 156   </refsect1>
 157
 158   <refsect1>
 159     <title>Return Value</title>
 160
 161     <para>On success, <function>sd_event_new()</function>, <function>sd_event_default()</function> and
 162     <function>sd_event_get_tid()</function> return 0 or a positive integer. On failure, they return a
 163     negative errno-style error code. <function>sd_event_ref()</function> always returns a pointer to the
 164     event loop object passed in. <function>sd_event_unref()</function> always returns
 165     <constant>NULL</constant>.</para>
 166
 167     <refsect2>
 168       <title>Errors</title>
 169
 170       <para>Returned errors may indicate the following problems:</para>
 171
 172       <variablelist>
 173         <varlistentry>
 174           <term><constant>-ENOMEM</constant></term>
 175
 176           <listitem><para>Not enough memory to allocate the object.</para></listitem>
 177         </varlistentry>
 178
 179         <varlistentry>
 180           <term><constant>-EMFILE</constant></term>
 181
 182           <listitem><para>The maximum number of event loops has been allocated.</para></listitem>
 183
 184         </varlistentry>
 185
 186         <varlistentry>
 187           <term><constant>-ENXIO</constant></term>
 188
 189           <listitem><para><function>sd_event_get_tid()</function> was invoked on an event loop object that
 190           was not allocated with <function>sd_event_default()</function>.</para></listitem>
 191         </varlistentry>
 192
 193       </variablelist>
 194     </refsect2>
 195   </refsect1>
 196
 197   <xi:include href="libsystemd-pkgconfig.xml" />
 198
 199   <refsect1>
 200     <title>See Also</title>
 201
 202     <para>
 203       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 204       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 205       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 206       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 207       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 208       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 209       <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 210       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 211       <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 212       <citerefentry project='man-pages'><refentrytitle>gettid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 213     </para>
 214   </refsect1>
 215
 216 </refentry>