sd_event_new.xml revision dc83f27a7cf03757dec11a69ec18504ad4ea8f89
3802a3d3d7af51ddff31943d5514382f01265770Lennart Poettering<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek This file is part of systemd.
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek Copyright 2014 Lennart Poettering
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek systemd is free software; you can redistribute it and/or modify it
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek under the terms of the GNU Lesser General Public License as published by
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek the Free Software Foundation; either version 2.1 of the License, or
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek (at your option) any later version.
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek systemd is distributed in the hope that it will be useful, but
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek WITHOUT ANY WARRANTY; without even the implied warranty of
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek Lesser General Public License for more details.
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek You should have received a copy of the GNU Lesser General Public License
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek along with systemd; If not, see <http://www.gnu.org/licenses/>.
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering<refentry id="sd_event_new" xmlns:xi="http://www.w3.org/2001/XInclude">
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <refentryinfo>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </authorgroup>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </refentryinfo>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <refentrytitle>sd_event_new</refentrytitle>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <refpurpose>Acquire and release an event loop object</refpurpose>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <refsynopsisdiv>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <funcsynopsis>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <funcsynopsisinfo><token>typedef</token> struct sd_event sd_event;</funcsynopsisinfo>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <funcprototype>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <funcdef>int <function>sd_event_new</function></funcdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <paramdef>sd_event **<parameter>event</parameter></paramdef>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </funcprototype>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <funcprototype>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <funcdef>int <function>sd_event_default</function></funcdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <paramdef>sd_event **<parameter>event</parameter></paramdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </funcprototype>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <funcprototype>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <funcdef>sd_event *<function>sd_event_ref</function></funcdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <paramdef>sd_event *<parameter>event</parameter></paramdef>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </funcprototype>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <funcprototype>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <funcdef>sd_event *<function>sd_event_unref</function></funcdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <paramdef>sd_event *<parameter>event</parameter></paramdef>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </funcprototype>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <funcprototype>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <funcdef>int <function>sd_event_get_tid</function></funcdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <paramdef>sd_event *<parameter>event</parameter></paramdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <paramdef>pid_t *<parameter>tid</parameter></paramdef>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </funcprototype>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </funcsynopsis>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </refsynopsisdiv>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <para><function>sd_event_new()</function> allocates a new event
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering loop object. The event loop object is returned in the
b8bde11658366290521e3d03316378b482600323Jan Engelhardt <parameter>event</parameter> parameter. After use, drop
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering the returned reference with
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <function>sd_event_unref()</function>. When the last reference is
bfe6c07e1b6bd8bf63d662c60fb333a003bb97a1Zbigniew Jędrzejewski-Szmek dropped, the object is freed.</para>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <para><function>sd_event_default()</function> acquires a reference
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering to the default event loop object of the calling thread, possibly
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering allocating a new object if no default event loop object has been
b8bde11658366290521e3d03316378b482600323Jan Engelhardt allocated yet for the thread. After use, drop the returned
a6ad1458e8baf913e9ee377c52863b927d7a2638Thomas Hindoe Paaboel Andersen reference with <function>sd_event_unref()</function>. When the
b8bde11658366290521e3d03316378b482600323Jan Engelhardt last reference is dropped, the event loop is freed. If this
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering function is called while the object returned from a previous call
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering from the same thread is still referenced, the same object is
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering returned again, but the reference is increased by one. It is
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering recommended to use this call instead of
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <function>sd_event_new()</function> in order to share event loop
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering objects between various components that are dispatched in the same
bfe6c07e1b6bd8bf63d662c60fb333a003bb97a1Zbigniew Jędrzejewski-Szmek thread. All threads have exactly either zero or one default event loop
bfe6c07e1b6bd8bf63d662c60fb333a003bb97a1Zbigniew Jędrzejewski-Szmek objects associated, but never more.</para>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para>After allocating an event loop object, add event sources to
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering and then execute the event loop using
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <para><function>sd_event_ref()</function> increases the reference
bfe6c07e1b6bd8bf63d662c60fb333a003bb97a1Zbigniew Jędrzejewski-Szmek count of the specified event loop object by one.</para>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <para><function>sd_event_unref()</function> decreases the
bfe6c07e1b6bd8bf63d662c60fb333a003bb97a1Zbigniew Jędrzejewski-Szmek reference count of the specified event loop object by one. If
bfe6c07e1b6bd8bf63d662c60fb333a003bb97a1Zbigniew Jędrzejewski-Szmek the count hits zero, the object is freed. Note that it
dca348bcbb462305864526c587495a14a76bfcdeJan Engelhardt is freed regardless of whether it is the default event loop object for a
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering thread or not. This means that allocating an event loop with
b8bde11658366290521e3d03316378b482600323Jan Engelhardt <function>sd_event_default()</function>, then releasing it, and
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering then acquiring a new one with
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <function>sd_event_default()</function> will result in two
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt distinct objects. Note that, in order to free an event loop object,
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering all remaining event sources of the event loop also need to be
bfe6c07e1b6bd8bf63d662c60fb333a003bb97a1Zbigniew Jędrzejewski-Szmek freed as each keeps a reference to it.</para>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para>Both <function>sd_event_ref()</function> and
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <function>sd_event_unref()</function> execute no operation if the
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering passed in event loop object is <constant>NULL</constant>.</para>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para><function>sd_event_get_tid()</function> retrieves the thread
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering identifier ("TID") of the thread the specified event loop object
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering is associated with. This call is only supported for event loops
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering allocated with <function>sd_event_default()</function>, and
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering returns the identifier for the thread the event loop is the
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering default event loop of. See <citerefentry
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering project='man-pages'><refentrytitle>gettid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering for more information on thread identifiers.</para>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <para>On success, <function>sd_event_new()</function> and
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <function>sd_event_default()</function> return 0 or a positive
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering integer. On failure, they return a negative errno-style error
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering code. <function>sd_event_ref()</function> always returns a pointer
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering to the event loop object passed
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering in. <function>sd_event_unref()</function> always returns
bfe6c07e1b6bd8bf63d662c60fb333a003bb97a1Zbigniew Jędrzejewski-Szmek <constant>NULL</constant>.</para>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <para>Returned errors may indicate the following problems:</para>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <variablelist>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <varlistentry>
8474b70c3a3842cdf3d51f331dd117ab6421f6d0Zbigniew Jędrzejewski-Szmek <term><constant>-ENOMEM</constant></term>
bfe6c07e1b6bd8bf63d662c60fb333a003bb97a1Zbigniew Jędrzejewski-Szmek <listitem><para>Not enough memory to allocate the object.</para></listitem>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </varlistentry>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <varlistentry>
8474b70c3a3842cdf3d51f331dd117ab6421f6d0Zbigniew Jędrzejewski-Szmek <term><constant>-EMFILE</constant></term>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <listitem><para>The maximum number of event loops has been allocated.</para></listitem>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </varlistentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <varlistentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <listitem><para><function>sd_event_get_tid()</function> was
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering invoked on an event loop object that was not allocated with
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <function>sd_event_default()</function>.</para></listitem>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </varlistentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </variablelist>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <xi:include href="libsystemd-pkgconfig.xml" />
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry project='man-pages'><refentrytitle>gettid</refentrytitle><manvolnum>2</manvolnum></citerefentry>