-<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
-<!--
- This file is part of systemd.
-
- Copyright 2015 Lennart Poettering
-
- systemd is free software; you can redistribute it and/or modify it
- under the terms of the GNU Lesser General Public License as published by
- the Free Software Foundation; either version 2.1 of the License, or
- (at your option) any later version.
-
- systemd is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- Lesser General Public License for more details.
-
- You should have received a copy of the GNU Lesser General Public License
- along with systemd; If not, see <http://www.gnu.org/licenses/>.
--->
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="sd_event_source_set_priority" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_source_set_priority</title>
<productname>systemd</productname>
-
- <authorgroup>
- <author>
- <contrib>Developer</contrib>
- <firstname>Lennart</firstname>
- <surname>Poettering</surname>
- <email>lennart@poettering.net</email>
- </author>
- </authorgroup>
</refentryinfo>
<refmeta>
<funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo>
<funcsynopsisinfo><token>enum</token> {
- <constant>SD_EVENT_SOURCE_IMPORTANT</constant> = -100,
- <constant>SD_EVENT_SOURCE_NORMAL</constant> = 0,
- <constant>SD_EVENT_SOURCE_IDLE</constant> = 100,
+ <constant>SD_EVENT_PRIORITY_IMPORTANT</constant> = -100,
+ <constant>SD_EVENT_PRIORITY_NORMAL</constant> = 0,
+ <constant>SD_EVENT_PRIORITY_IDLE</constant> = 100,
};</funcsynopsisinfo>
<funcprototype>
<constant>SD_EVENT_PRIORITY_IDLE</constant> (100) may be used to
indicate event sources that shall be dispatched early, normally or
late. It is recommended to specify priorities based on these
- definitions, and relative to them -- however, the full 64bit
+ definitions, and relative to them — however, the full 64bit
signed integer range is available for ordering event
sources.</para>
dispatched is undefined, but the event loop generally tries to
dispatch them in the order it learnt about events on them. As the
backing kernel primitives do not provide accurate information
- about the order in which events occured this is not necessarily
+ about the order in which events occurred this is not necessarily
reliable. However, it is guaranteed that if events are seen on
multiple same-priority event sources at the same time, each one is
not dispatched again until all others have been dispatched
- once. This behaviour guarantees that within each priority
+ once. This behavior guarantees that within each priority
particular event sources do not starve or dominate the event
loop.</para>
+ <para>The priority of event sources may be changed at any time of their lifetime, with the exception of inotify
+ event sources (i.e. those created with
+ <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>) whose
+ priority may only be changed in the time between their initial creation and the first subsequent event loop
+ iteration.</para>
+
<para><function>sd_event_source_get_priority()</function> may be
used to query the current priority assigned to the event source
object <parameter>source</parameter>.</para>
<refsect1>
<title>Return Value</title>
- <para>On success,
- <function>sd_event_source_set_priority()</function> and
- <function>sd_event_source_get_priority()</function> return a
- non-negative integer. On failure, they return a negative
- errno-style error code.</para>
- </refsect1>
+ <para>On success, <function>sd_event_source_set_priority()</function> and
+ <function>sd_event_source_get_priority()</function> return a non-negative integer. On failure, they
+ return a negative errno-style error code.</para>
- <refsect1>
- <title>Errors</title>
+ <refsect2>
+ <title>Errors</title>
- <para>Returned errors may indicate the following problems:</para>
+ <para>Returned errors may indicate the following problems:</para>
- <variablelist>
- <varlistentry>
- <term><constant>-EINVAL</constant></term>
+ <variablelist>
+ <varlistentry>
+ <term><constant>-EINVAL</constant></term>
- <listitem><para><parameter>source</parameter> is not a valid
- pointer to an <structname>sd_event_source</structname>
- object.</para></listitem>
- </varlistentry>
+ <listitem><para><parameter>source</parameter> is not a valid pointer to an
+ <structname>sd_event_source</structname> object.</para></listitem>
+ </varlistentry>
- <varlistentry>
- <term><constant>-ENOMEM</constant></term>
+ <varlistentry>
+ <term><constant>-ENOMEM</constant></term>
- <listitem><para>Not enough memory.</para></listitem>
- </varlistentry>
+ <listitem><para>Not enough memory.</para></listitem>
+ </varlistentry>
- <varlistentry>
- <term><constant>-ESTALE</constant></term>
+ <varlistentry>
+ <term><constant>-ESTALE</constant></term>
- <listitem><para>The event loop is already terminated.</para></listitem>
+ <listitem><para>The event loop is already terminated.</para></listitem>
- </varlistentry>
+ </varlistentry>
- <varlistentry>
- <term><constant>-ECHILD</constant></term>
+ <varlistentry>
+ <term><constant>-ECHILD</constant></term>
- <listitem><para>The event loop has been created in a different process.</para></listitem>
+ <listitem><para>The event loop has been created in a different process.</para></listitem>
- </varlistentry>
+ </varlistentry>
- </variablelist>
+ </variablelist>
+ </refsect2>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>