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     <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 105     <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 106     <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry> or
 107     <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 108     and then execute the event loop using
 109     <citerefentry><refentrytitle>sd_event_loop</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 110
 111     <para><function>sd_event_ref()</function> increases the reference
 112     count of the specified event loop object by one.</para>
 113
 114     <para><function>sd_event_unref()</function> decreases the
 115     reference count of the specified event loop object by one. If
 116     the count hits zero, the object is freed. Note that it
 117     is freed regardless of whether it is the default event loop object for a
 118     thread or not. This means that allocating an event loop with
 119     <function>sd_event_default()</function>, then releasing it, and
 120     then acquiring a new one with
 121     <function>sd_event_default()</function> will result in two
 122     distinct objects. Note that, in order to free an event loop object,
 123     all remaining event sources of the event loop also need to be
 124     freed as each keeps a reference to it.</para>
 125
 126     <para><function>sd_event_unrefp()</function> is similar to
 127     <function>sd_event_unref()</function> but takes a pointer to a
 128     pointer to an <type>sd_event</type> object. This call is useful in
 129     conjunction with GCC's and LLVM's <ulink
 130     url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
 131     Variable Attribute</ulink>. Note that this function is defined as
 132     inline function. Use a declaration like the following,
 133     in order to allocate an event loop object that is freed
 134     automatically as the code block is left:</para>
 135
 136     <programlisting>{
 137         __attribute__((cleanup(sd_event_unrefp)) sd_event *event = NULL;
 138         int r;
 139         …
 140         r = sd_event_default(&amp;event);
 141         if (r &lt; 0)
 142                 fprintf(stderr, "Failed to allocate event loop: %s\n", strerror(-r));
 143         …
 144 }</programlisting>
 145
 146     <para><function>sd_event_ref()</function>,
 147     <function>sd_event_unref()</function> and
 148     <function>sd_event_unrefp()</function> execute no operation if the
 149     passed in event loop object is <constant>NULL</constant>.</para>
 150
 151     <para><function>sd_event_get_tid()</function> retrieves the thread
 152     identifier ("TID") of the thread the specified event loop object
 153     is associated with. This call is only supported for event loops
 154     allocated with <function>sd_event_default()</function>, and
 155     returns the identifier for the thread the event loop is the
 156     default event loop of. See <citerefentry
 157     project='man-pages'><refentrytitle>gettid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 158     for more information on thread identifiers.</para>
 159   </refsect1>
 160
 161   <refsect1>
 162     <title>Return Value</title>
 163
 164     <para>On success, <function>sd_event_new()</function>,
 165     <function>sd_event_default()</function> and
 166     <function>sd_event_get_tid()</function> return 0 or a positive
 167     integer. On failure, they return a negative errno-style error
 168     code. <function>sd_event_ref()</function> always returns a pointer
 169     to the event loop object passed
 170     in. <function>sd_event_unref()</function> always returns
 171     <constant>NULL</constant>.</para>
 172   </refsect1>
 173
 174   <refsect1>
 175     <title>Errors</title>
 176
 177     <para>Returned errors may indicate the following problems:</para>
 178
 179     <variablelist>
 180       <varlistentry>
 181         <term><constant>-ENOMEM</constant></term>
 182
 183         <listitem><para>Not enough memory to allocate the object.</para></listitem>
 184       </varlistentry>
 185
 186       <varlistentry>
 187         <term><constant>-EMFILE</constant></term>
 188
 189         <listitem><para>The maximum number of event loops has been allocated.</para></listitem>
 190
 191       </varlistentry>
 192
 193       <varlistentry>
 194         <term><constant>-ENXIO</constant></term>
 195
 196         <listitem><para><function>sd_event_get_tid()</function> was
 197         invoked on an event loop object that was not allocated with
 198         <function>sd_event_default()</function>.</para></listitem>
 199       </varlistentry>
 200
 201     </variablelist>
 202   </refsect1>
 203
 204   <xi:include href="libsystemd-pkgconfig.xml" />
 205
 206   <refsect1>
 207     <title>See Also</title>
 208
 209     <para>
 210       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 211       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 212       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 213       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 214       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 215       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 216       <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 217       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 218       <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 219       <citerefentry project='man-pages'><refentrytitle>gettid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 220     </para>
 221   </refsect1>
 222
 223 </refentry>