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