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" conditional="ENABLE_KDBUS">
  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
  51     <refpurpose>Acquire and release an event loop object</refpurpose>
  52   </refnamediv>
  53
  54   <refsynopsisdiv>
  55     <funcsynopsis>
  56       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  57
  58       <funcprototype>
  59         <funcdef>int <function>sd_event_new</function></funcdef>
  60         <paramdef>sd_bus **<parameter>event</parameter></paramdef>
  61       </funcprototype>
  62
  63       <funcprototype>
  64         <funcdef>int <function>sd_event_default</function></funcdef>
  65         <paramdef>sd_bus **<parameter>event</parameter></paramdef>
  66       </funcprototype>
  67
  68       <funcprototype>
  69         <funcdef>sd_bus *<function>sd_event_ref</function></funcdef>
  70         <paramdef>sd_bus *<parameter>event</parameter></paramdef>
  71       </funcprototype>
  72
  73       <funcprototype>
  74         <funcdef>sd_bus *<function>sd_event_unref</function></funcdef>
  75         <paramdef>sd_bus *<parameter>event</parameter></paramdef>
  76       </funcprototype>
  77
  78     </funcsynopsis>
  79   </refsynopsisdiv>
  80
  81   <refsect1>
  82     <title>Description</title>
  83
  84     <para><function>sd_event_new()</function> allocates a new event
  85     loop object. The event loop object is returned in the
  86     <parameter>event</parameter> parameter. After use, drop
  87     the returned reference with
  88     <function>sd_event_unref()</function>. When the last reference is
  89     dropped, the object is freed.</para>
  90
  91     <para><function>sd_event_default()</function> acquires a reference
  92     to the default event loop object of the calling thread, possibly
  93     allocating a new object if no default event loop object has been
  94     allocated yet for the thread. After use, drop the returned
  95     reference with <function>sd_event_unref()</function>. When the
  96     last reference is dropped, the event loop is freed. If this
  97     function is called while the object returned from a previous call
  98     from the same thread is still referenced, the same object is
  99     returned again, but the reference is increased by one. It is
 100     recommended to use this call instead of
 101     <function>sd_event_new()</function> in order to share event loop
 102     objects between various components that are dispatched in the same
 103     thread. All threads have exactly either zero or one default event loop
 104     objects associated, but never more.</para>
 105
 106     <para><function>sd_event_ref()</function> increases the reference
 107     count of the specified event loop object by one.</para>
 108
 109     <para><function>sd_event_unref()</function> decreases the
 110     reference count of the specified event loop object by one. If
 111     the count hits zero, the object is freed. Note that it
 112     is freed regardless of whether it is the default event loop object for a
 113     thread or not. This means that allocating an event loop with
 114     <function>sd_event_default()</function>, then releasing it, and
 115     then acquiring a new one with
 116     <function>sd_event_default()</function> will result in two
 117     distinct objects. Note that in order to free an event loop object,
 118     all remaining event sources of the event loop also need to be
 119     freed as each keeps a reference to it.</para>
 120   </refsect1>
 121
 122   <refsect1>
 123     <title>Return Value</title>
 124
 125     <para>On success, <function>sd_event_new()</function> and
 126     <function>sd_event_default()</function> return 0 or a positive
 127     integer. On failure, they return a negative errno-style error
 128     code. <function>sd_event_ref()</function> always returns a pointer
 129     to the event loop object passed
 130     in. <function>sd_event_unref()</function> always returns
 131     <constant>NULL</constant>.</para>
 132   </refsect1>
 133
 134   <refsect1>
 135     <title>Errors</title>
 136
 137     <para>Returned errors may indicate the following problems:</para>
 138
 139     <variablelist>
 140       <varlistentry>
 141         <term><constant>-ENOMEM</constant></term>
 142
 143         <listitem><para>Not enough memory to allocate the object.</para></listitem>
 144       </varlistentry>
 145
 146       <varlistentry>
 147         <term><constant>-EMFILE</constant></term>
 148
 149         <listitem><para>The maximum number of event loops has been allocated.</para></listitem>
 150
 151       </varlistentry>
 152     </variablelist>
 153   </refsect1>
 154
 155   <refsect1>
 156     <title>Notes</title>
 157
 158     <para><function>sd_event_new()</function> and the other functions
 159     described here are available as a shared library, which can be
 160     compiled and linked to with the
 161     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 162     file.</para>
 163   </refsect1>
 164
 165   <refsect1>
 166     <title>See Also</title>
 167
 168     <para>
 169       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 170       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 171       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 172       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 173       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 174       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 175       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 176       <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 177       <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 178     </para>
 179   </refsect1>
 180
 181 </refentry>