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   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="sd_event_add_defer" xmlns:xi="http://www.w3.org/2001/XInclude">
  10
  11   <refentryinfo>
  12     <title>sd_event_add_defer</title>
  13     <productname>systemd</productname>
  14   </refentryinfo>
  15
  16   <refmeta>
  17     <refentrytitle>sd_event_add_defer</refentrytitle>
  18     <manvolnum>3</manvolnum>
  19   </refmeta>
  20
  21   <refnamediv>
  22     <refname>sd_event_add_defer</refname>
  23     <refname>sd_event_add_post</refname>
  24     <refname>sd_event_add_exit</refname>
  25     <refname>sd_event_handler_t</refname>
  26
  27     <refpurpose>Add static event sources to an event loop</refpurpose>
  28   </refnamediv>
  29
  30   <refsynopsisdiv>
  31     <funcsynopsis>
  32       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  33
  34       <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
  35
  36       <funcprototype>
  37         <funcdef>typedef int (*<function>sd_event_handler_t</function>)</funcdef>
  38         <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
  39         <paramdef>void *<parameter>userdata</parameter></paramdef>
  40       </funcprototype>
  41
  42       <funcprototype>
  43         <funcdef>int <function>sd_event_add_defer</function></funcdef>
  44         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  45         <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
  46         <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef>
  47         <paramdef>void *<parameter>userdata</parameter></paramdef>
  48       </funcprototype>
  49
  50       <funcprototype>
  51         <funcdef>int <function>sd_event_add_post</function></funcdef>
  52         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  53         <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
  54         <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef>
  55         <paramdef>void *<parameter>userdata</parameter></paramdef>
  56       </funcprototype>
  57
  58       <funcprototype>
  59         <funcdef>int <function>sd_event_add_exit</function></funcdef>
  60         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  61         <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
  62         <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef>
  63         <paramdef>void *<parameter>userdata</parameter></paramdef>
  64       </funcprototype>
  65
  66     </funcsynopsis>
  67   </refsynopsisdiv>
  68
  69   <refsect1>
  70     <title>Description</title>
  71
  72     <para>These three functions add new static event sources to an
  73     event loop. The event loop object is specified in the
  74     <parameter>event</parameter> parameter, the event source object is
  75     returned in the <parameter>source</parameter> parameter. The event
  76     sources are enabled statically and will "fire" when the event loop
  77     is run and the conditions described below are met. The handler
  78     function will be passed the <parameter>userdata</parameter>
  79     pointer, which may be chosen freely by the caller.</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
 110     will be disabled after the invocation, even if the
 111     <constant>SD_EVENT_ON</constant> mode was requested before.</para>
 112
 113     <para>To destroy an event source object use
 114     <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 115     but note that the event source is only removed from the event loop
 116     when all references to the event source are dropped. To make sure
 117     an event source does not fire anymore, even when there's still a
 118     reference to it kept, consider setting the event source to
 119     <constant>SD_EVENT_OFF</constant> with
 120     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 121
 122     <para>If the second parameter of these functions is passed as
 123     NULL no reference to the event source object is returned. In this
 124     case the event source is considered "floating", and will be
 125     destroyed implicitly when the event loop itself is
 126     destroyed.</para>
 127   </refsect1>
 128
 129   <refsect1>
 130     <title>Return Value</title>
 131
 132     <para>On success, these functions return 0 or a positive
 133     integer. On failure, they return a negative errno-style error
 134     code.</para>
 135   </refsect1>
 136
 137   <refsect1>
 138     <title>Errors</title>
 139
 140     <para>Returned errors may indicate the following problems:</para>
 141
 142     <variablelist>
 143       <varlistentry>
 144         <term><constant>-ENOMEM</constant></term>
 145
 146         <listitem><para>Not enough memory to allocate an object.</para></listitem>
 147       </varlistentry>
 148
 149       <varlistentry>
 150         <term><constant>-EINVAL</constant></term>
 151
 152         <listitem><para>An invalid argument has been passed.</para></listitem>
 153       </varlistentry>
 154
 155       <varlistentry>
 156         <term><constant>-ESTALE</constant></term>
 157
 158         <listitem><para>The event loop is already terminated.</para></listitem>
 159       </varlistentry>
 160
 161       <varlistentry>
 162         <term><constant>-ECHILD</constant></term>
 163
 164         <listitem><para>The event loop has been created in a different process.</para></listitem>
 165       </varlistentry>
 166
 167     </variablelist>
 168   </refsect1>
 169
 170   <xi:include href="libelogind-pkgconfig.xml" />
 171
 172   <refsect1>
 173     <title>See Also</title>
 174
 175     <para>
 176       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 177       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 178       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 179       <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 180       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 181       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 182       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 183       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 184       <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 185       <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 186       <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 187       <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 188       <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 189       <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 190     </para>
 191   </refsect1>
 192
 193 </refentry>