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