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 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   This file is part of systemd.
  10
  11   Copyright 2014 Lennart Poettering
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="sd_event_new" conditional="ENABLE_KDBUS">
  28
  29   <refentryinfo>
  30     <title>sd_event_new</title>
  31     <productname>systemd</productname>
  32
  33     <authorgroup>
  34       <author>
  35         <contrib>Developer</contrib>
  36         <firstname>Lennart</firstname>
  37         <surname>Poettering</surname>
  38         <email>lennart@poettering.net</email>
  39       </author>
  40     </authorgroup>
  41   </refentryinfo>
  42
  43   <refmeta>
  44     <refentrytitle>sd_event_new</refentrytitle>
  45     <manvolnum>3</manvolnum>
  46   </refmeta>
  47
  48   <refnamediv>
  49     <refname>sd_event_new</refname>
  50     <refname>sd_event_default</refname>
  51     <refname>sd_event_ref</refname>
  52     <refname>sd_event_unref</refname>
  53
  54     <refpurpose>Acquire and release an event loop object</refpurpose>
  55   </refnamediv>
  56
  57   <refsynopsisdiv>
  58     <funcsynopsis>
  59       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  60
  61       <funcprototype>
  62         <funcdef>int <function>sd_event_new</function></funcdef>
  63         <paramdef>sd_bus **<parameter>event</parameter></paramdef>
  64       </funcprototype>
  65
  66       <funcprototype>
  67         <funcdef>int <function>sd_event_default</function></funcdef>
  68         <paramdef>sd_bus **<parameter>event</parameter></paramdef>
  69       </funcprototype>
  70
  71       <funcprototype>
  72         <funcdef>sd_bus *<function>sd_event_ref</function></funcdef>
  73         <paramdef>sd_bus *<parameter>event</parameter></paramdef>
  74       </funcprototype>
  75
  76       <funcprototype>
  77         <funcdef>sd_bus *<function>sd_event_unref</function></funcdef>
  78         <paramdef>sd_bus *<parameter>event</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><function>sd_event_ref()</function> increases the reference
 110     count of the specified event loop object by one.</para>
 111
 112     <para><function>sd_event_unref()</function> decreases the
 113     reference count of the specified event loop object by one. If
 114     the count hits zero, the object is freed. Note that it
 115     is freed regardless of whether it is the default event loop object for a
 116     thread or not. This means that allocating an event loop with
 117     <function>sd_event_default()</function>, then releasing it, and
 118     then acquiring a new one with
 119     <function>sd_event_default()</function> will result in two
 120     distinct objects. Note that in order to free an event loop object,
 121     all remaining event sources of the event loop also need to be
 122     freed as each keeps a reference to it.</para>
 123   </refsect1>
 124
 125   <refsect1>
 126     <title>Return Value</title>
 127
 128     <para>On success, <function>sd_event_new()</function> and
 129     <function>sd_event_default()</function> return 0 or a positive
 130     integer. On failure, they return a negative errno-style error
 131     code. <function>sd_event_ref()</function> always returns a pointer
 132     to the event loop object passed
 133     in. <function>sd_event_unref()</function> always returns
 134     <constant>NULL</constant>.</para>
 135   </refsect1>
 136
 137   <refsect1>
 138     <title>Errors</title>
 139
 140     <para>Returned errors may indicate the following problems:</para>
 141
 142     <variablelist>
 143       <varlistentry>
 144         <term><constant>-ENOMEM</constant></term>
 145
 146         <listitem><para>Not enough memory to allocate the object.</para></listitem>
 147       </varlistentry>
 148
 149       <varlistentry>
 150         <term><constant>-EMFILE</constant></term>
 151
 152         <listitem><para>The maximum number of event loops has been allocated.</para></listitem>
 153
 154       </varlistentry>
 155     </variablelist>
 156   </refsect1>
 157
 158   <refsect1>
 159     <title>Notes</title>
 160
 161     <para><function>sd_event_new()</function> and the other functions
 162     described here are available as a shared library, which can be
 163     compiled and linked to with the
 164     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 165     file.</para>
 166   </refsect1>
 167
 168   <refsect1>
 169     <title>See Also</title>
 170
 171     <para>
 172       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 173       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 174       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 175       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 176       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 177       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 178       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 179       <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 180       <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 181     </para>
 182   </refsect1>
 183
 184 </refentry>