man/sd-event.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 2015 Lennart Poettering
   9 -->
  10
  11 <refentry id="sd-event" xmlns:xi="http://www.w3.org/2001/XInclude">
  12
  13   <refentryinfo>
  14     <title>sd-event</title>
  15     <productname>elogind</productname>
  16
  17     <authorgroup>
  18       <author>
  19         <contrib>Developer</contrib>
  20         <firstname>Lennart</firstname>
  21         <surname>Poettering</surname>
  22         <email>lennart@poettering.net</email>
  23       </author>
  24     </authorgroup>
  25   </refentryinfo>
  26
  27   <refmeta>
  28     <refentrytitle>sd-event</refentrytitle>
  29     <manvolnum>3</manvolnum>
  30   </refmeta>
  31
  32   <refnamediv>
  33     <refname>sd-event</refname>
  34     <refpurpose>A generic event loop implementation</refpurpose>
  35   </refnamediv>
  36
  37   <refsynopsisdiv>
  38     <funcsynopsis>
  39       <funcsynopsisinfo>#include &lt;elogind/sd-event.h&gt;</funcsynopsisinfo>
  40     </funcsynopsis>
  41
  42     <cmdsynopsis>
  43       <command>pkg-config --cflags --libs libelogind</command>
  44     </cmdsynopsis>
  45
  46   </refsynopsisdiv>
  47
  48   <refsect1>
  49     <title>Description</title>
  50
  51     <para><filename>sd-event.h</filename> provides a generic event
  52     loop implementation, based on Linux <citerefentry
  53     project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
  54     </para>
  55
  56     <para>See
  57     <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  58     <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  59     <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  60     <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  61     <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  62     <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  63     <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  64     <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  65     <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  66     <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  67     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  68     <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  69     <citerefentry><refentrytitle>sd_event_source_get_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  70     <citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  71     <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  72     <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  73     <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  74     <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  75     <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  76     <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  77     <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  78     for more information about the functions available.</para>
  79
  80     <para>The event loop design is targeted on running a separate
  81     instance of the event loop in each thread; it has no concept of
  82     distributing events from a single event loop instance onto
  83     multiple worker threads. Dispatching events is strictly ordered
  84     and subject to configurable priorities. In each event loop
  85     iteration a single event source is dispatched. Each time an event
  86     source is dispatched the kernel is polled for new events, before
  87     the next event source is dispatched. The event loop is designed to
  88     honor priorities and provide fairness within each priority. It is
  89     not designed to provide optimal throughput, as this contradicts
  90     these goals due the limitations of the underlying <citerefentry
  91     project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>
  92     primitives.</para>
  93
  94     <para>The event loop implementation provides the following features:</para>
  95
  96     <orderedlist>
  97       <listitem><para>I/O event sources, based on <citerefentry
  98       project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>'s
  99       file descriptor watching, including edge triggered events (<constant>EPOLLET</constant>). See <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
 100
 101       <listitem><para>Timer event sources, based on <citerefentry
 102       project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 103       supporting the <constant>CLOCK_MONOTONIC</constant>,
 104       <constant>CLOCK_REALTIME</constant>,
 105       <constant>CLOCK_BOOTIME</constant> clocks, as well as the
 106       <constant>CLOCK_REALTIME_ALARM</constant> and
 107       <constant>CLOCK_BOOTTIME_ALARM</constant> clocks that can resume
 108       the system from suspend. When creating timer events a required
 109       accuracy parameter may be specified which allows coalescing of
 110       timer events to minimize power consumption. See <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
 111
 112       <listitem><para>UNIX process signal events, based on
 113       <citerefentry
 114       project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 115       including full support for real-time signals, and queued parameters. See <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
 116
 117       <listitem><para>Child process state change events, based on
 118       <citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>. See <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
 119
 120       <listitem><para>Static event sources, of three types: defer,
 121       post and exit, for invoking calls in each event loop, after
 122       other event sources or at event loop termination. See
 123       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
 124
 125       <listitem><para>Event sources may be assigned a 64bit priority
 126       value, that controls the order in which event sources are
 127       dispatched if multiple are pending simultaneously. See
 128       <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
 129
 130       <listitem><para>The event loop may automatically send watchdog
 131       notification messages to the service manager. See
 132       <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
 133
 134       <listitem><para>The event loop may be integrated into foreign
 135       event loops, such as the GLib one. See
 136       <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 137       for an example.</para></listitem>
 138     </orderedlist>
 139
 140   </refsect1>
 141
 142   <xi:include href="libelogind-pkgconfig.xml" />
 143
 144   <refsect1>
 145     <title>See Also</title>
 146     <para>
 147       <!-- 0 /// elogind is in section 8
 148       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 149       <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 150       --><!-- else -->
 151       <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 152       <!-- // 0 -->
 153       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 154       <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 155       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 156       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 157       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 158       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 159       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 160       <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 161       <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 162       <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 163       <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 164       <citerefentry><refentrytitle>sd_event_source_get_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 165       <citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 166       <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 167       <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 168       <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 169       <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 170       <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 171       <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 172       <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 173       <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 174       <citerefentry project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 175       <citerefentry project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 176       <citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 177     </para>
 178   </refsect1>
 179
 180 </refentry>