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".

2 files changed, 25 insertions, 38 deletions

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
diff --git a/src/libsystemd/sd-event/sd-event.c b/src/libsystemd/sd-event/sd-event.c
index 8552d5a54e..eeb3453919 100644
--- a/src/libsystemd/sd-event/sd-event.c
+++ b/src/libsystemd/sd-event/sd-event.c
@@ -1070,7 +1070,6 @@ _public_ int sd_event_add_time(
         int r;
 
         assert_return(e, -EINVAL);
-        assert_return(usec != (uint64_t) -1, -EINVAL);
         assert_return(accuracy != (uint64_t) -1, -EINVAL);
         assert_return(e->state != SD_EVENT_FINISHED, -ESTALE);
         assert_return(!event_pid_changed(e), -ECHILD);
@@ -1760,7 +1759,6 @@ _public_ int sd_event_source_set_time(sd_event_source *s, uint64_t usec) {
         struct clock_data *d;
 
         assert_return(s, -EINVAL);
-        assert_return(usec != (uint64_t) -1, -EINVAL);
         assert_return(EVENT_SOURCE_IS_TIME(s->type), -EDOM);
         assert_return(s->event->state != SD_EVENT_FINISHED, -ESTALE);
         assert_return(!event_pid_changed(s->event), -ECHILD);
@@ -1890,6 +1888,8 @@ static usec_t sleep_between(sd_event *e, usec_t a, usec_t b) {
 
         if (a <= 0)
                 return 0;
+        if (a >= USEC_INFINITY)
+                return USEC_INFINITY;
 
         if (b <= a + 1)
                 return a;
@@ -1979,7 +1979,7 @@ static int event_arm_timer(
                 d->needs_rearm = false;
 
         a = prioq_peek(d->earliest);
-        if (!a || a->enabled == SD_EVENT_OFF) {
+        if (!a || a->enabled == SD_EVENT_OFF || a->time.next == USEC_INFINITY) {
 
                 if (d->fd < 0)
                         return 0;