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