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