sd_event_new.xml revision b8bde11658366290521e3d03316378b482600323
8a77240a809197c92c0736c431b4b88947a7bac1Christian Maeder<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
8a77240a809197c92c0736c431b4b88947a7bac1Christian Maeder"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
09b431a868c79a92ae7c9bd141565f43f9034144Christian MaederThis file is part of systemd.
98890889ffb2e8f6f722b00e265a211f13b5a861Corneliu-Claudiu ProdescuCopyright 2014 Lennart Poettering
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowskisystemd is free software; you can redistribute it and/or modify it
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowskiunder the terms of the GNU Lesser General Public License as published by
f3a94a197960e548ecd6520bb768cb0d547457bbChristian Maederthe Free Software Foundation; either version 2.1 of the License, or
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder(at your option) any later version.
adea2e45fa61f1097aadc490a0aeaf4831b729ccChristian Maedersystemd is distributed in the hope that it will be useful, but
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till MossakowskiWITHOUT ANY WARRANTY; without even the implied warranty of
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till MossakowskiMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
09b431a868c79a92ae7c9bd141565f43f9034144Christian MaederLesser General Public License for more details.
09b431a868c79a92ae7c9bd141565f43f9034144Christian MaederYou should have received a copy of the GNU Lesser General Public License
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowskialong with systemd; If not, see <http://www.gnu.org/licenses/>.
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski<refentry id="sd_event_new" conditional="ENABLE_KDBUS">
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <refentryinfo>
ad270004874ce1d0697fb30d7309f180553bb315Christian Maeder <authorgroup>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski </authorgroup>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski </refentryinfo>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <refentrytitle>sd_event_new</refentrytitle>
556f473448dfcceee22afaa89ed7a364489cdbbbChristian Maeder <refpurpose>Acquire and release an event loop object</refpurpose>
556f473448dfcceee22afaa89ed7a364489cdbbbChristian Maeder </refnamediv>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <refsynopsisdiv>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <funcsynopsis>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <funcprototype>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <funcdef>int <function>sd_event_new</function></funcdef>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <paramdef>sd_bus **<parameter>event</parameter></paramdef>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski </funcprototype>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <funcprototype>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <funcdef>int <function>sd_event_default</function></funcdef>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <paramdef>sd_bus **<parameter>event</parameter></paramdef>
adea2e45fa61f1097aadc490a0aeaf4831b729ccChristian Maeder </funcprototype>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <funcprototype>
adea2e45fa61f1097aadc490a0aeaf4831b729ccChristian Maeder <funcdef>sd_bus *<function>sd_event_ref</function></funcdef>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <paramdef>sd_bus *<parameter>event</parameter></paramdef>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder </funcprototype>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <funcprototype>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <funcdef>sd_bus *<function>sd_event_unref</function></funcdef>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <paramdef>sd_bus *<parameter>event</parameter></paramdef>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski </funcprototype>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski </funcsynopsis>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder </refsynopsisdiv>
556f473448dfcceee22afaa89ed7a364489cdbbbChristian Maeder <para><function>sd_event_new()</function> allocates a new event
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski loop object. The event loop object is returned in the
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <parameter>event</parameter> parameter. After use, drop
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski the returned reference with
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <function>sd_event_unref()</function>. When the last reference is
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski dropped, the event loop is freed.</para>
4ef5e33657aae95850b7e6941f67ac1fb73cd13fChristian Maeder <para><function>sd_event_default()</function> acquires a reference
4ef5e33657aae95850b7e6941f67ac1fb73cd13fChristian Maeder to the default event loop object of the calling thread, possibly
e7d2b3903c7b44db432538b0d720c21062c24823Christian Maeder allocating a new object if no default event loop object has been
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski allocated yet for the thread. After use, drop the returned
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski reference with <function>sd_event_unref()</function>. When the
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski last reference is dropped, the event loop is freed. If this
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder function is called while the object returned from a previous call
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski from the same thread is still referenced, the same object is
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski returned again, but the reference is increased by one. It is
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski recommended to use this call instead of
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <function>sd_event_new()</function> in order to share event loop
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski objects between various components that are dispatched in the same
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski thread. All threads either have exactly zero or one default event loop
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder associated, but never more.</para>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <para><function>sd_event_ref()</function> increases the reference
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski counter of the specified event loop object by one.</para>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <para><function>sd_event_unref()</function> decreases the
a98fd29a06e80e447af26d898044c23497adbc73Mihai Codescu reference counter of the specified event loop object by one. If
a98fd29a06e80e447af26d898044c23497adbc73Mihai Codescu the counter hits zero, the event loop object is freed. Note that it
a98fd29a06e80e447af26d898044c23497adbc73Mihai Codescu is freed regardless of whether it is the default event loop object for a
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski thread or not. This means that allocating an event loop with
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <function>sd_event_default()</function>, then releasing it, and
e7d2b3903c7b44db432538b0d720c21062c24823Christian Maeder then acquiring a new one with
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <function>sd_event_default()</function> will result in two
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski distinct objects. Note that, in order to free an event loop object,
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski all remaining event sources of the event loop also need to be
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski freed as they each keep a reference to it.</para>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <para>On success, <function>sd_event_new()</function> and
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <function>sd_event_default()</function> return 0 or a positive
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski integer. On failure, they return a negative errno-style error
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder code. <function>sd_event_ref()</function> always returns a pointer
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski to the event loop object passed
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder in. <function>sd_event_unref()</function> always returns
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <para>Returned errors may indicate the following problems:</para>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <variablelist>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <varlistentry>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <listitem><para>Not enough memory to allocate object</para></listitem>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder </varlistentry>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <varlistentry>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <listitem><para>The maximum number of event loops has been allocated.</para></listitem>
556f473448dfcceee22afaa89ed7a364489cdbbbChristian Maeder </varlistentry>
556f473448dfcceee22afaa89ed7a364489cdbbbChristian Maeder </variablelist>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <para><function>sd_event_new()</function> and the other functions
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder described here are available as a shared library, which can be
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder compiled and linked to with the
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
556f473448dfcceee22afaa89ed7a364489cdbbbChristian Maeder <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>