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