man/sd_event_add_defer.xml

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