From 393003e1debf7c7f75beaacbd532b92c3e3dc729 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Mon, 1 Feb 2016 00:20:18 +0100
Subject: sd-event: permit a USEC_INFINITY timeout as an alternative to a
 disabling an event source

This should simplify handling of time events in clients and is in-line with the USEC_INFINITY macro we already have.
This way setting a timeout to 0 indicates "elapse immediately", and a timeout of USEC_INFINITY "elapse never".
---
 man/sd_event_add_time.xml | 57 ++++++++++++++++++-----------------------------
 1 file changed, 22 insertions(+), 35 deletions(-)

(limited to 'man')

diff --git a/man/sd_event_add_time.xml b/man/sd_event_add_time.xml
index 142fa80f8f..a2c0d54b56 100644
--- a/man/sd_event_add_time.xml
+++ b/man/sd_event_add_time.xml
@@ -114,41 +114,28 @@
   <refsect1>
     <title>Description</title>
 
-    <para><function>sd_event_add_time()</function> adds a new timer
-    event source to an event loop. The event loop object is specified
-    in the <parameter>event</parameter> parameter, the event source
-    object is returned in the <parameter>source</parameter>
-    parameter. The <parameter>clock</parameter> parameter takes a
-    clock identifier, one of <constant>CLOCK_REALTIME</constant>,
-    <constant>CLOCK_MONOTONIC</constant>,
-    <constant>CLOCK_BOOTTIME</constant>,
-    <constant>CLOCK_REALTIME_ALARM</constant>, or
-    <constant>CLOCK_BOOTTIME_ALARM</constant>. See
-    <citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>
-    for details regarding the various types of clocks. The
-    <parameter>usec</parameter> parameter specifies the earliest time,
-    in microseconds (µs), relative to the clock's epoch, when
-    the timer shall be triggered. If a time already in the past is
-    specified (including <constant>0</constant>), this timer source
-    "fires" immediately and is ready to be dispatched. The
-    <parameter>accuracy</parameter> parameter specifies an additional
-    accuracy value in µs specifying how much the timer event may be
-    delayed. Use <constant>0</constant> to select the default accuracy
-    (250ms). Use 1µs for maximum accuracy. Consider specifying
-    60000000µs (1min) or larger for long-running events that may be
-    delayed substantially. Picking higher accuracy values allows the
-    system to coalesce timer events more aggressively, improving
-    power efficiency. The <parameter>handler</parameter> parameter
-    shall reference a function to call when the timer elapses. The
-    handler function will be passed the
-    <parameter>userdata</parameter> pointer, which may be chosen
-    freely by the caller. The handler is also passed the configured
-    trigger time, even if it is actually called
-    slightly later, subject to the specified accuracy value,
-    the kernel timer slack (see
-    <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>),
-    and additional scheduling latencies. To query the actual time the
-    handler was called use
+    <para><function>sd_event_add_time()</function> adds a new timer event source to an event loop. The event loop
+    object is specified in the <parameter>event</parameter> parameter, the event source object is returned in the
+    <parameter>source</parameter> parameter. The <parameter>clock</parameter> parameter takes a clock identifier, one
+    of <constant>CLOCK_REALTIME</constant>, <constant>CLOCK_MONOTONIC</constant>, <constant>CLOCK_BOOTTIME</constant>,
+    <constant>CLOCK_REALTIME_ALARM</constant>, or <constant>CLOCK_BOOTTIME_ALARM</constant>. See
+    <citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details
+    regarding the various types of clocks. The <parameter>usec</parameter> parameter specifies the earliest time, in
+    microseconds (µs), relative to the clock's epoch, when the timer shall be triggered. If a time already in the past
+    is specified (including <constant>0</constant>), this timer source "fires" immediately and is ready to be
+    dispatched. If the paramater is specified as <constant>UINT64_MAX</constant> the timer event will never elapse,
+    which may be used as an alternative to explicitly disabling a timer event source with
+    <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The
+    <parameter>accuracy</parameter> parameter specifies an additional accuracy value in µs specifying how much the
+    timer event may be delayed. Use <constant>0</constant> to select the default accuracy (250ms). Use 1µs for maximum
+    accuracy. Consider specifying 60000000µs (1min) or larger for long-running events that may be delayed
+    substantially. Picking higher accuracy values allows the system to coalesce timer events more aggressively,
+    improving power efficiency. The <parameter>handler</parameter> parameter shall reference a function to call when
+    the timer elapses. The handler function will be passed the <parameter>userdata</parameter> pointer, which may be
+    chosen freely by the caller. The handler is also passed the configured trigger time, even if it is actually called
+    slightly later, subject to the specified accuracy value, the kernel timer slack (see
+    <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>), and additional
+    scheduling latencies. To query the actual time the handler was called use
     <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 
     <para>By default, the timer will elapse once
-- 
cgit v1.2.3