man/sd_event_source_set_priority.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="sd_event_source_set_priority" xmlns:xi="http://www.w3.org/2001/XInclude">
   7
   8   <refentryinfo>
   9     <title>sd_event_source_set_priority</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>sd_event_source_set_priority</refentrytitle>
  15     <manvolnum>3</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>sd_event_source_set_priority</refname>
  20     <refname>sd_event_source_get_priority</refname>
  21     <refname>SD_EVENT_PRIORITY_IMPORTANT</refname>
  22     <refname>SD_EVENT_PRIORITY_NORMAL</refname>
  23     <refname>SD_EVENT_PRIORITY_IDLE</refname>
  24
  25     <refpurpose>Set or retrieve the priority of event sources</refpurpose>
  26   </refnamediv>
  27
  28   <refsynopsisdiv>
  29     <funcsynopsis>
  30       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  31
  32       <funcsynopsisinfo><token>enum</token> {
  33         <constant>SD_EVENT_PRIORITY_IMPORTANT</constant> = -100,
  34         <constant>SD_EVENT_PRIORITY_NORMAL</constant> = 0,
  35         <constant>SD_EVENT_PRIORITY_IDLE</constant> = 100,
  36 };</funcsynopsisinfo>
  37
  38       <funcprototype>
  39         <funcdef>int <function>sd_event_source_set_priority</function></funcdef>
  40         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  41         <paramdef>int64_t <parameter>priority</parameter></paramdef>
  42       </funcprototype>
  43
  44       <funcprototype>
  45         <funcdef>int <function>sd_event_source_get_priority</function></funcdef>
  46         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  47         <paramdef>int64_t *<parameter>priority</parameter></paramdef>
  48       </funcprototype>
  49
  50     </funcsynopsis>
  51   </refsynopsisdiv>
  52
  53   <refsect1>
  54     <title>Description</title>
  55
  56     <para><function>sd_event_source_set_priority()</function> may be
  57     used to set the priority for the event source object specified as
  58     <parameter>source</parameter>. The priority is specified as an
  59     arbitrary signed 64-bit integer. The priority is initialized to
  60     <constant>SD_EVENT_PRIORITY_NORMAL</constant> (0) when the event
  61     source is allocated with a call such as
  62     <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  63     or
  64     <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  65     and may be changed with this call. If multiple event sources have seen events at the same time, they are dispatched in the order indicated by the
  66     event sources' priorities. Event sources with smaller priority
  67     values are dispatched first. As well-known points of reference,
  68     the constants <constant>SD_EVENT_PRIORITY_IMPORTANT</constant>
  69     (-100), <constant>SD_EVENT_PRIORITY_NORMAL</constant> (0) and
  70     <constant>SD_EVENT_PRIORITY_IDLE</constant> (100) may be used to
  71     indicate event sources that shall be dispatched early, normally or
  72     late. It is recommended to specify priorities based on these
  73     definitions, and relative to them — however, the full 64-bit
  74     signed integer range is available for ordering event
  75     sources.</para>
  76
  77     <para>Priorities define the order in which event sources that have
  78     seen events are dispatched. Care should be taken to ensure that
  79     high-priority event sources (those with negative priority values
  80     assigned) do not cause starvation of low-priority event sources
  81     (those with positive priority values assigned).</para>
  82
  83     <para>The order in which event sources with the same priority are
  84     dispatched is undefined, but the event loop generally tries to
  85     dispatch them in the order it learnt about events on them. As the
  86     backing kernel primitives do not provide accurate information
  87     about the order in which events occurred this is not necessarily
  88     reliable. However, it is guaranteed that if events are seen on
  89     multiple same-priority event sources at the same time, each one is
  90     not dispatched again until all others have been dispatched
  91     once. This behavior guarantees that within each priority
  92     particular event sources do not starve or dominate the event
  93     loop.</para>
  94
  95     <para>The priority of event sources may be changed at any time of their lifetime, with the exception of inotify
  96     event sources (i.e. those created with
  97     <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>) whose
  98     priority may only be changed in the time between their initial creation and the first subsequent event loop
  99     iteration.</para>
 100
 101     <para><function>sd_event_source_get_priority()</function> may be
 102     used to query the current priority assigned to the event source
 103     object <parameter>source</parameter>.</para>
 104   </refsect1>
 105
 106   <refsect1>
 107     <title>Return Value</title>
 108
 109     <para>On success, <function>sd_event_source_set_priority()</function> and
 110     <function>sd_event_source_get_priority()</function> return a non-negative integer. On failure, they
 111     return a negative errno-style error code.</para>
 112
 113     <refsect2>
 114       <title>Errors</title>
 115
 116       <para>Returned errors may indicate the following problems:</para>
 117
 118       <variablelist>
 119         <varlistentry>
 120           <term><constant>-EINVAL</constant></term>
 121
 122           <listitem><para><parameter>source</parameter> is not a valid pointer to an
 123           <structname>sd_event_source</structname> object.</para></listitem>
 124         </varlistentry>
 125
 126         <varlistentry>
 127           <term><constant>-ENOMEM</constant></term>
 128
 129           <listitem><para>Not enough memory.</para></listitem>
 130         </varlistentry>
 131
 132         <varlistentry>
 133           <term><constant>-ESTALE</constant></term>
 134
 135           <listitem><para>The event loop is already terminated.</para></listitem>
 136
 137         </varlistentry>
 138
 139         <varlistentry>
 140           <term><constant>-ECHILD</constant></term>
 141
 142           <listitem><para>The event loop has been created in a different process, library or module instance.</para></listitem>
 143
 144         </varlistentry>
 145
 146       </variablelist>
 147     </refsect2>
 148   </refsect1>
 149
 150   <xi:include href="libsystemd-pkgconfig.xml" />
 151
 152   <refsect1>
 153     <title>History</title>
 154     <para><function>sd_event_source_set_priority()</function> and
 155     <function>sd_event_source_get_priority()</function> were added in version 229.</para>
 156   </refsect1>
 157
 158   <refsect1>
 159     <title>See Also</title>
 160
 161     <para>
 162       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 163       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 164       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 165       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 166       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 167       <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 168       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 169     </para>
 170   </refsect1>
 171
 172 </refentry>