man/sd_event_source_set_priority.xml

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