man/sd_event_source_set_priority.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 2015 Lennart Poettering
  11
  12   systemd is free software; you can redistribute it and/or modify it
  13   under the terms of the GNU Lesser General Public License as published by
  14   the Free Software Foundation; either version 2.1 of the License, or
  15   (at your option) any later version.
  16
  17   systemd is distributed in the hope that it will be useful, but
  18   WITHOUT ANY WARRANTY; without even the implied warranty of
  19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  20   Lesser General Public License for more details.
  21
  22   You should have received a copy of the GNU Lesser General Public License
  23   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  24 -->
  25
  26 <refentry id="sd_event_source_set_priority" xmlns:xi="http://www.w3.org/2001/XInclude">
  27
  28   <refentryinfo>
  29     <title>sd_event_source_set_priority</title>
  30     <productname>systemd</productname>
  31
  32     <authorgroup>
  33       <author>
  34         <contrib>Developer</contrib>
  35         <firstname>Lennart</firstname>
  36         <surname>Poettering</surname>
  37         <email>lennart@poettering.net</email>
  38       </author>
  39     </authorgroup>
  40   </refentryinfo>
  41
  42   <refmeta>
  43     <refentrytitle>sd_event_source_set_priority</refentrytitle>
  44     <manvolnum>3</manvolnum>
  45   </refmeta>
  46
  47   <refnamediv>
  48     <refname>sd_event_source_set_priority</refname>
  49     <refname>sd_event_source_get_priority</refname>
  50     <refname>SD_EVENT_PRIORITY_IMPORTANT</refname>
  51     <refname>SD_EVENT_PRIORITY_NORMAL</refname>
  52     <refname>SD_EVENT_PRIORITY_IDLE</refname>
  53
  54     <refpurpose>Set or retrieve the priority of event sources</refpurpose>
  55   </refnamediv>
  56
  57   <refsynopsisdiv>
  58     <funcsynopsis>
  59       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  60
  61       <funcsynopsisinfo><token>enum</token> {
  62         <constant>SD_EVENT_PRIORITY_IMPORTANT</constant> = -100,
  63         <constant>SD_EVENT_PRIORITY_NORMAL</constant> = 0,
  64         <constant>SD_EVENT_PRIORITY_IDLE</constant> = 100,
  65 };</funcsynopsisinfo>
  66
  67       <funcprototype>
  68         <funcdef>int <function>sd_event_source_set_priority</function></funcdef>
  69         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  70         <paramdef>int64_t <parameter>priority</parameter></paramdef>
  71       </funcprototype>
  72
  73       <funcprototype>
  74         <funcdef>int <function>sd_event_source_get_priority</function></funcdef>
  75         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  76         <paramdef>int64_t *<parameter>priority</parameter></paramdef>
  77       </funcprototype>
  78
  79     </funcsynopsis>
  80   </refsynopsisdiv>
  81
  82   <refsect1>
  83     <title>Description</title>
  84
  85     <para><function>sd_event_source_set_priority()</function> may be
  86     used to set the priority for the event source object specified as
  87     <parameter>source</parameter>. The priority is specified as an
  88     arbitrary signed 64bit integer. The priority is initialized to
  89     <constant>SD_EVENT_PRIORITY_NORMAL</constant> (0) when the event
  90     source is allocated with a call such as
  91     <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  92     or
  93     <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  94     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
  95     event sources' priorities. Event sources with smaller priority
  96     values are dispatched first. As well-known points of reference,
  97     the constants <constant>SD_EVENT_PRIORITY_IMPORTANT</constant>
  98     (-100), <constant>SD_EVENT_PRIORITY_NORMAL</constant> (0) and
  99     <constant>SD_EVENT_PRIORITY_IDLE</constant> (100) may be used to
 100     indicate event sources that shall be dispatched early, normally or
 101     late. It is recommended to specify priorities based on these
 102     definitions, and relative to them — however, the full 64bit
 103     signed integer range is available for ordering event
 104     sources.</para>
 105
 106     <para>Priorities define the order in which event sources that have
 107     seen events are dispatched. Care should be taken to ensure that
 108     high-priority event sources (those with negative priority values
 109     assigned) do not cause starvation of low-priority event sources
 110     (those with positive priority values assigned).</para>
 111
 112     <para>The order in which event sources with the same priority are
 113     dispatched is undefined, but the event loop generally tries to
 114     dispatch them in the order it learnt about events on them. As the
 115     backing kernel primitives do not provide accurate information
 116     about the order in which events occurred this is not necessarily
 117     reliable. However, it is guaranteed that if events are seen on
 118     multiple same-priority event sources at the same time, each one is
 119     not dispatched again until all others have been dispatched
 120     once. This behavior guarantees that within each priority
 121     particular event sources do not starve or dominate the event
 122     loop.</para>
 123
 124     <para><function>sd_event_source_get_priority()</function> may be
 125     used to query the current priority assigned to the event source
 126     object <parameter>source</parameter>.</para>
 127   </refsect1>
 128
 129   <refsect1>
 130     <title>Return Value</title>
 131
 132     <para>On success,
 133     <function>sd_event_source_set_priority()</function> and
 134     <function>sd_event_source_get_priority()</function> return a
 135     non-negative integer. On failure, they return a negative
 136     errno-style error code.</para>
 137   </refsect1>
 138
 139   <refsect1>
 140     <title>Errors</title>
 141
 142     <para>Returned errors may indicate the following problems:</para>
 143
 144     <variablelist>
 145       <varlistentry>
 146         <term><constant>-EINVAL</constant></term>
 147
 148         <listitem><para><parameter>source</parameter> is not a valid
 149         pointer to an <structname>sd_event_source</structname>
 150         object.</para></listitem>
 151       </varlistentry>
 152
 153       <varlistentry>
 154         <term><constant>-ENOMEM</constant></term>
 155
 156         <listitem><para>Not enough memory.</para></listitem>
 157       </varlistentry>
 158
 159       <varlistentry>
 160         <term><constant>-ESTALE</constant></term>
 161
 162         <listitem><para>The event loop is already terminated.</para></listitem>
 163
 164       </varlistentry>
 165
 166       <varlistentry>
 167         <term><constant>-ECHILD</constant></term>
 168
 169         <listitem><para>The event loop has been created in a different process.</para></listitem>
 170
 171       </varlistentry>
 172
 173     </variablelist>
 174   </refsect1>
 175
 176   <xi:include href="libsystemd-pkgconfig.xml" />
 177
 178   <refsect1>
 179     <title>See Also</title>
 180
 181     <para>
 182       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 183       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 184       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 185       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 186       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 187       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 188     </para>
 189   </refsect1>
 190
 191 </refentry>