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