man/sd_event_new.xml

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