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