man/sd_event_add_defer.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 Zbigniew Jędrzejewski-Szmek
   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_add_defer" xmlns:xi="http://www.w3.org/2001/XInclude">
  25
  26   <refentryinfo>
  27     <title>sd_event_add_defer</title>
  28     <productname>systemd</productname>
  29
  30     <authorgroup>
  31       <author>
  32         <contrib>More text</contrib>
  33         <firstname>Zbigniew</firstname>
  34         <surname>Jędrzejewski-Szmek</surname>
  35         <email>zbyszek@in.waw.pl</email>
  36       </author>
  37     </authorgroup>
  38   </refentryinfo>
  39
  40   <refmeta>
  41     <refentrytitle>sd_event_add_defer</refentrytitle>
  42     <manvolnum>3</manvolnum>
  43   </refmeta>
  44
  45   <refnamediv>
  46     <refname>sd_event_add_defer</refname>
  47     <refname>sd_event_add_post</refname>
  48     <refname>sd_event_add_exit</refname>
  49     <refname>sd_event_handler_t</refname>
  50
  51     <refpurpose>Add static event sources to an event loop</refpurpose>
  52   </refnamediv>
  53
  54   <refsynopsisdiv>
  55     <funcsynopsis>
  56       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  57
  58       <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
  59
  60       <funcprototype>
  61         <funcdef>typedef int (*<function>sd_event_handler_t</function>)</funcdef>
  62         <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
  63         <paramdef>void *<parameter>userdata</parameter></paramdef>
  64       </funcprototype>
  65
  66       <funcprototype>
  67         <funcdef>int <function>sd_event_add_defer</function></funcdef>
  68         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  69         <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
  70         <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef>
  71         <paramdef>void *<parameter>userdata</parameter></paramdef>
  72       </funcprototype>
  73
  74       <funcprototype>
  75         <funcdef>int <function>sd_event_add_post</function></funcdef>
  76         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  77         <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
  78         <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef>
  79         <paramdef>void *<parameter>userdata</parameter></paramdef>
  80       </funcprototype>
  81
  82       <funcprototype>
  83         <funcdef>int <function>sd_event_add_exit</function></funcdef>
  84         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  85         <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
  86         <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef>
  87         <paramdef>void *<parameter>userdata</parameter></paramdef>
  88       </funcprototype>
  89
  90     </funcsynopsis>
  91   </refsynopsisdiv>
  92
  93   <refsect1>
  94     <title>Description</title>
  95
  96     <para>These three functions add new static event sources to an
  97     event loop. The event loop object is specified in the
  98     <parameter>event</parameter> parameter, the event source object is
  99     returned in the <parameter>source</parameter> parameter. The event
 100     sources are enabled statically and will "fire" when the event loop
 101     is run and the conditions described below are met. The handler
 102     function will be passed the <parameter>userdata</parameter>
 103     pointer, which may be chosen freely by the caller.</para>
 104
 105     <para><function>sd_event_add_defer()</function> adds a new event
 106     source that will be dispatched instantly, before the event loop
 107     goes to sleep again and waits for new events. By default, the
 108     handler will be called once
 109     (<constant>SD_EVENT_ONESHOT</constant>). Note that if the event
 110     source is set to <constant>SD_EVENT_ON</constant> the event loop
 111     will never go to sleep again, but continuously call the handler,
 112     possibly interleaved with other event sources.</para>
 113
 114     <para><function>sd_event_add_post()</function> adds a new event
 115     source that is run before the event loop will sleep and wait
 116     for new events, but only after at least one other non-post event
 117     source was dispatched. By default, the source is enabled
 118     permanently (<constant>SD_EVENT_ON</constant>). Note that this
 119     event source type will still allow the event loop to go to sleep
 120     again, even if set to <constant>SD_EVENT_ON</constant>, as long as
 121     no other event source is ever triggered.</para>
 122
 123     <para><function>sd_event_add_exit()</function> adds a new event
 124     source that will be dispatched when the event loop is terminated
 125     with <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 126
 127     <para>The
 128     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 129     function may be used to enable the event source permanently
 130     (<constant>SD_EVENT_ON</constant>) or to make it fire just once
 131     (<constant>SD_EVENT_ONESHOT</constant>).</para>
 132
 133     <para>If the handler function returns a negative error code, it
 134     will be disabled after the invocation, even if the
 135     <constant>SD_EVENT_ON</constant> mode was requested before.</para>
 136
 137     <para>To destroy an event source object use
 138     <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 139     but note that the event source is only removed from the event loop
 140     when all references to the event source are dropped. To make sure
 141     an event source does not fire anymore, even when there's still a
 142     reference to it kept, consider setting the event source to
 143     <constant>SD_EVENT_OFF</constant> with
 144     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 145
 146     <para>If the second parameter of these functions is passed as
 147     NULL no reference to the event source object is returned. In this
 148     case the event source is considered "floating", and will be
 149     destroyed implicitly when the event loop itself is
 150     destroyed.</para>
 151   </refsect1>
 152
 153   <refsect1>
 154     <title>Return Value</title>
 155
 156     <para>On success, this functions return 0 or a positive
 157     integer. On failure, they return a negative errno-style error
 158     code.</para>
 159   </refsect1>
 160
 161   <refsect1>
 162     <title>Errors</title>
 163
 164     <para>Returned errors may indicate the following problems:</para>
 165
 166     <variablelist>
 167       <varlistentry>
 168         <term><constant>-ENOMEM</constant></term>
 169
 170         <listitem><para>Not enough memory to allocate an object.</para></listitem>
 171       </varlistentry>
 172
 173       <varlistentry>
 174         <term><constant>-EINVAL</constant></term>
 175
 176         <listitem><para>An invalid argument has been passed.</para></listitem>
 177       </varlistentry>
 178
 179       <varlistentry>
 180         <term><constant>-ESTALE</constant></term>
 181
 182         <listitem><para>The event loop is already terminated.</para></listitem>
 183       </varlistentry>
 184
 185       <varlistentry>
 186         <term><constant>-ECHILD</constant></term>
 187
 188         <listitem><para>The event loop has been created in a different process.</para></listitem>
 189       </varlistentry>
 190
 191     </variablelist>
 192   </refsect1>
 193
 194   <xi:include href="libsystemd-pkgconfig.xml" />
 195
 196   <refsect1>
 197     <title>See Also</title>
 198
 199     <para>
 200       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 201       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 202       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 203       <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 204       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 205       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 206       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 207       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 208       <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 209       <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 210       <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 211       <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 212       <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 213     </para>
 214   </refsect1>
 215
 216 </refentry>