Skip to contentSkip to conversation

Document/cleanup event_timeout functions

PATCH Superseded Arne Schwabe 3 participants 6 messages Sep 23, 2022 – Oct 7, 2022

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 Document/cleanup event_timeout functions

Remove function event_timeout_clear_ret as it is unused.

Cleanup event_timeout_trigger a bit. Do an instant return false if the timeout is not defined and inline local_now and use event_timeout_remaining instead of local duplicated code.

Add doxygen comments for all timeout function, especially for the event_timeout_trigger function that is hard to understand otherwise.

---
 src/openvpn/interval.c | 50 ++++++++++++-----------
 src/openvpn/interval.h | 92 +++++++++++++++++++++++++++++-------------
 src/openvpn/openvpn.h  |  4 +-
 3 files changed, 92 insertions(+), 54 deletions(-)
src/openvpn/interval.c +26 -24
index 2f0fc42dd..8f3c1c604 100644
@@ -41,44 +41,46 @@ interval_init(struct interval *top, int horizon, int refresh)
     top->horizon = horizon;
 }
 
+
 bool
 event_timeout_trigger(struct event_timeout *et,
                       struct timeval *tv,
                       const int et_const_retry)
 {
+    if (!et->defined)
+    {
+        return false;
+    }
+
     bool ret = false;
-    const time_t local_now = now;
+    time_t wakeup = event_timeout_remaining(et);
 
-    if (et->defined)
+    if (wakeup <= 0)
     {
-        time_t wakeup = et->last - local_now + et->n;
-        if (wakeup <= 0)
-        {
 #if INTERVAL_DEBUG
-            dmsg(D_INTERVAL, "EVENT event_timeout_trigger (%d) etcr=%d", et->n,
-                 et_const_retry);
+        dmsg(D_INTERVAL, "EVENT event_timeout_trigger (%d) etcr=%d", et->n,
+             et_const_retry);
 #endif
-            if (et_const_retry < 0)
-            {
-                et->last = local_now;
-                wakeup = et->n;
-                ret = true;
-            }
-            else
-            {
-                wakeup = et_const_retry;
-            }
+        if (et_const_retry < 0)
+        {
+            et->last = now;
+            wakeup = et->n;
+            ret = true;
         }
-
-        if (tv && wakeup < tv->tv_sec)
+        else
         {
+            wakeup = et_const_retry;
+        }
+    }
+
+    if (tv && wakeup < tv->tv_sec)
+    {
 #if INTERVAL_DEBUG
-            dmsg(D_INTERVAL, "EVENT event_timeout_wakeup (%d/%d) etcr=%d",
-                 (int) wakeup, et->n, et_const_retry);
+        dmsg(D_INTERVAL, "EVENT event_timeout_wakeup (%d/%d) etcr=%d",
+             (int) wakeup, et->n, et_const_retry);
 #endif
-            tv->tv_sec = wakeup;
-            tv->tv_usec = 0;
-        }
+        tv->tv_sec = wakeup;
+        tv->tv_usec = 0;
     }
     return ret;
 }
src/openvpn/interval.h +63 -29

139 lines not on this page · raw message

src/openvpn/openvpn.h +3 -1
index 00cd652fa..aae1d21b8 100644
@@ -386,7 +386,9 @@ struct context_2
      * Event loop info
      */
 
-    /* how long to wait on link/tun read before we will need to be serviced */
+    /* time to next event of timers and similar. This is used to determine
+     * how long to wait on event wait (select/poll on link/tun read)
+     * before this context wants to be serviced */
     struct timeval timeval;
 
     /* next wakeup for processing coarse timers (>1 sec resolution) */
Signature · 1 line
2.37.0 (Apple Git-136)
#1 lore raw
Quoted 5 lines · Arne Schwabe

Remove function event_timeout_clear_ret as it is unused.

Cleanup event_timeout_trigger a bit. Do an instant return false if the timeout is not defined and inline local_now and use event_timeout_remaining instead of local duplicated code.

That part best seen with git diff -w ;)
Changes look good to me.

Quoted 2 lines

Add doxygen comments for all timeout function, especially for the event_timeout_trigger function that is hard to understand otherwise.

Some comments on those below.

Quoted 35 lines
src/openvpn/interval.h +9 -4
index f58bfacf6..f6e40705c 100644
@@ -135,9 +135,9 @@ interval_action(struct interval *top)
 
 struct event_timeout
 {
-    bool defined;
-    interval_t n;
-    time_t last; /* time of last event */
+    bool defined;       /**< This timeout is active */
+    interval_t n;       /**< periodic interval for periodic timeouts */
+    time_t last;        /**< time of last event */
 };
 
 static inline bool
@@ -145,7 +145,12 @@ event_timeout_defined(const struct event_timeout *et)
 {
     return et->defined;
 }
-
+/**
+ * Clears the timeout and reset all values to 0. Following timer checks will
+ * not trigger.
+ *
+ * @param et    timer struct
+ */
 static inline void
 event_timeout_clear(struct event_timeout *et)
 {
@@ -154,22 +159,30 @@ event_timeout_clear(struct event_timeout *et)
     et->last = 0;
 }
 

src/openvpn/interval.h event_timeout_clear(struct event_timeout *et) · line 164

Quoted 10 lines
src/openvpn/interval.h +2 -7
-static inline struct event_timeout
-event_timeout_clear_ret(void)
-{
-    struct event_timeout ret;
-    event_timeout_clear(&ret);
-    return ret;
-}
 
+/**
+ * Initialises a timer struct. The timer will become true/trigger after last + n seconds

Add period for consistency.

src/openvpn/interval.h event_timeout_clear(struct event_timeout *et) · line 168

Quoted 4 lines
src/openvpn/interval.h +4 -0
+ *
+ *
+ * @param et            Timer struct
+ * @param n             Interval of the timer for periodic timer. A negative value for n will be interpreted as 0

Add period for consistency. Wrap text? 113 is a bit broad.

Quoted 4 lines
src/openvpn/interval.h +2 -1
+ * @param last          Sets the base time of the timer.
+ */
 static inline void
-event_timeout_init(struct event_timeout *et, interval_t n, const time_t local_now)

src/openvpn/interval.h event_timeout_clear(struct event_timeout *et) · line 180

Quoted 10 lines
src/openvpn/interval.h +4 -1
+event_timeout_init(struct event_timeout *et, interval_t n, const time_t last)
 {
     et->defined = true;
     et->n = (n >= 0) ? n : 0;
-    et->last = local_now;
+    et->last = last;
 }
 
+/**
+ * Reset a timer.

"Resets" for consistency.

Quoted 9 lines
src/openvpn/interval.h +5 -0
+ *
+ * Sets the last time the timer has been triggered for the calculation of the
+ * next event.
+ * @param et
+ */
 static inline void
 event_timeout_reset(struct event_timeout *et)
 {

src/openvpn/interval.h event_timeout_reset(struct event_timeout *et) · line 196

Quoted 5 lines
src/openvpn/interval.h +2 -0
@@ -179,6 +192,12 @@ event_timeout_reset(struct event_timeout *et)
     }
 }
 
+/**
+ * Sets the periodic parameter n of a timeout.

"interval" instead of "periodic parameter" for consistency?

src/openvpn/interval.h event_timeout_reset(struct event_timeout *et) · line 199

Quoted 3 lines
src/openvpn/interval.h +3 -0
+ * @param et
+ * @param n set the periodic value of a timeout, negative values
+ *          will be interpreted as 0

Redundant description. Maybe more like

* @param n Interval of the timer. A negative value for n will be interpreted as 0

src/openvpn/interval.h event_timeout_reset(struct event_timeout *et) · line 203

Quoted 4 lines
src/openvpn/interval.h +1 -0
+ */
 static inline void
 event_timeout_modify_wakeup(struct event_timeout *et, interval_t n)
 {

Just below here there is an additional comment inside the function:
/* note that you might need to call reset_coarse_timers after this */

That should be moved into the doxygen comment.

src/openvpn/interval.h event_timeout_modify_wakeup(struct event_timeout *et, interval_t n) · line 214

Quoted 11 lines
src/openvpn/interval.h +3 -3
@@ -189,32 +208,47 @@ event_timeout_modify_wakeup(struct event_timeout *et, interval_t n)
     }
 }
 
-/*
- * Will return the time left for a timeout, this function does not check
- * if the timeout is actually valid
+/**
+ * Return time until the timeout should triggered from from now,
+ * this function does not check if the timeout is actually valid.
  */

"Returns" for consistency.
"now, this" -> "now. This"

Quoted 26 lines
src/openvpn/interval.h +7 -12
 static inline interval_t
 event_timeout_remaining(struct event_timeout *et)
 {
-    return (interval_t) (et->last - now + et->n);
+    return (interval_t) ((et->last + et->n) - now);
 }
 
-/*
- * This is the principal function for testing and triggering recurring
- * timers and will return true on a timer signal event.
- * If et_const_retry == ETT_DEFAULT and a signal occurs,
- * the function will return true and *et will be armed for the
- * next event.  If et_const_retry >= 0 and a signal occurs,
- * *et will not be touched, but *tv will be set to
- * minimum (*tv, et_const_retry) for a future re-test,
- * and the function will return true.
- */
-
 #define ETT_DEFAULT (-1)
 
+/**
+ * This is the principal function for testing and triggering recurring
+ * timers.
+ *
+ * If *et is not triggered *tv is set to remaining time until the timeout if
+ * not already lower:

src/openvpn/interval.h event_timeout_modify_wakeup(struct event_timeout *et, interval_t n) · line 238

Quoted 10 lines
src/openvpn/interval.h +10 -0
+ *
+ *      *tv = minimum(*tv, event_timeout_remaining(*et))
+ *
+ * If *et triggers and et_const_retry is negative (ETT_DEFAULT is -1):
+ *  - the function will return true
+ *  - *et will be armed for the next event (et->last set to now).
+ *  - *tv will be lowered to the event period (n) if larger than the
+ *     period of the event (set to *et's next timeout)
+ *
+ * If *et triggers and et_const_retry >= 0, *tv be reduced to et_const_try if

"will be"

src/openvpn/interval.h event_timeout_modify_wakeup(struct event_timeout *et, interval_t n) · line 241

Quoted 3 lines
src/openvpn/interval.h +3 -0
+ * larger:
+ *
+ *    *tv = *minimum(*tv, et_const_retry)

I think this should explicitly mention that et is NOT re-armed and explain why you would want to use that.

src/openvpn/interval.h event_timeout_modify_wakeup(struct event_timeout *et, interval_t n) · line 245

Quoted 4 lines
src/openvpn/interval.h +4 -0
+ *
+ *
+ * @param et                the timeout to check
+ * @param tv                will be set to timeout for next check for this timeout unless already small.

"smaller"

src/openvpn/interval.h event_timeout_modify_wakeup(struct event_timeout *et, interval_t n) · line 246

Quoted 1 line
src/openvpn/interval.h +1 -0
+ * @param et_const_retry    see above

"above" does not actually explain why you would use this. See above ;)

src/openvpn/interval.h event_timeout_modify_wakeup(struct event_timeout *et, interval_t n) · line 248

Quoted 2 lines
src/openvpn/interval.h +2 -0
+ * @return                  if the timeout has triggered and event has been reset
+ */

You're mixing lowered/lower and reduced/larger/smaller. I think it would be better to only use one of those.

src/openvpn/interval.h event_timeout_modify_wakeup(struct event_timeout *et, interval_t n) · line 251

Quoted 4 lines
src/openvpn/interval.h +1 -1
 bool event_timeout_trigger(struct event_timeout *et,
                            struct timeval *tv,
-                           const int et_const_retry);
+                           int et_const_retry);

Why remove the const here? You did not remove it in interval.c

src/openvpn/openvpn.h struct context_2 · line 389

Quoted 13 lines
src/openvpn/interval.h +0 -0
 /*
  * Measure time intervals in microseconds
src/openvpn/openvpn.h +1 -1
index 00cd652fa..aae1d21b8 100644
@@ -386,7 +386,9 @@ struct context_2
      * Event loop info
      */
 
-    /* how long to wait on link/tun read before we will need to be serviced */
+    /* time to next event of timers and similar. This is used to determine

"Time"

src/openvpn/openvpn.h struct context_2 · line 391

Quoted 2 lines
src/openvpn/openvpn.h +2 -0
+     * how long to wait on event wait (select/poll on link/tun read)
+     * before this context wants to be serviced */

Add period for consistency

Quoted 5 lines
src/openvpn/openvpn.h +0 -0
     struct timeval timeval;
 
     /* next wakeup for processing coarse timers (>1 sec resolution) */
Signature · 1 line
2.37.0 (Apple Git-136)

Regards,

Signature · 1 line
  Frank Lichtenheld
#3 lore raw

PATCH v2 1/1 Document/cleanup event_timeout functions

In reply to Arne Schwabe

Remove function event_timeout_clear_ret as it is unused.

Cleanup event_timeout_trigger a bit. Do an instant return false if the timeout is not defined and inline local_now and use event_timeout_remaining instead of local duplicated code.

Add doxygen comments for all timeout function, especially for the event_timeout_trigger function that is hard to understand otherwise.

Patch v2: add many fixes/correction suggested by Frank

---
 src/openvpn/interval.c |  50 ++++++++++----------
 src/openvpn/interval.h | 103 +++++++++++++++++++++++++++++------------
 src/openvpn/openvpn.h  |   4 +-
 3 files changed, 102 insertions(+), 55 deletions(-)
src/openvpn/interval.c +26 -24
index 2f0fc42dd..8f3c1c604 100644
@@ -41,44 +41,46 @@ interval_init(struct interval *top, int horizon, int refresh)
     top->horizon = horizon;
 }
 
+
 bool
 event_timeout_trigger(struct event_timeout *et,
                       struct timeval *tv,
                       const int et_const_retry)
 {
+    if (!et->defined)
+    {
+        return false;
+    }
+
     bool ret = false;
-    const time_t local_now = now;
+    time_t wakeup = event_timeout_remaining(et);
 
-    if (et->defined)
+    if (wakeup <= 0)
     {
-        time_t wakeup = et->last - local_now + et->n;
-        if (wakeup <= 0)
-        {
 #if INTERVAL_DEBUG
-            dmsg(D_INTERVAL, "EVENT event_timeout_trigger (%d) etcr=%d", et->n,
-                 et_const_retry);
+        dmsg(D_INTERVAL, "EVENT event_timeout_trigger (%d) etcr=%d", et->n,
+             et_const_retry);
 #endif
-            if (et_const_retry < 0)
-            {
-                et->last = local_now;
-                wakeup = et->n;
-                ret = true;
-            }
-            else
-            {
-                wakeup = et_const_retry;
-            }
+        if (et_const_retry < 0)
+        {
+            et->last = now;
+            wakeup = et->n;
+            ret = true;
         }
-
-        if (tv && wakeup < tv->tv_sec)
+        else
         {
+            wakeup = et_const_retry;
+        }
+    }
+
+    if (tv && wakeup < tv->tv_sec)
+    {
 #if INTERVAL_DEBUG
-            dmsg(D_INTERVAL, "EVENT event_timeout_wakeup (%d/%d) etcr=%d",
-                 (int) wakeup, et->n, et_const_retry);
+        dmsg(D_INTERVAL, "EVENT event_timeout_wakeup (%d/%d) etcr=%d",
+             (int) wakeup, et->n, et_const_retry);
 #endif
-            tv->tv_sec = wakeup;
-            tv->tv_usec = 0;
-        }
+        tv->tv_sec = wakeup;
+        tv->tv_usec = 0;
     }
     return ret;
 }
src/openvpn/interval.h +73 -30

153 lines not on this page · raw message

src/openvpn/openvpn.h +3 -1
index 00cd652fa..95c7d7520 100644
@@ -386,7 +386,9 @@ struct context_2
      * Event loop info
      */
 
-    /* how long to wait on link/tun read before we will need to be serviced */
+    /** Time to next event of timers and similar. This is used to determine
+     *  how long to wait on event wait (select/poll on link/tun read)
+     *  before this context wants to be serviced */
     struct timeval timeval;
 
     /* next wakeup for processing coarse timers (>1 sec resolution) */
Signature · 1 line
2.37.0 (Apple Git-136)
#2 lore raw
In reply to Frank Lichtenheld

Am 23.09.22 um 12:12 schrieb Frank Lichtenheld:

Quoted 7 lines

src/openvpn/interval.h event_timeout_modify_wakeup(struct event_timeout *et, interval_t n) · line 251

Quoted 5 lines

bool event_timeout_trigger(struct event_timeout *et,
struct timeval *tv,

src/openvpn/interval.h +1 -1
-                           const int et_const_retry);
+                           int et_const_retry);

Why remove the const here? You did not remove it in interval.c

clang-tidy complains here. The reason is that the const is doing nothing in the prototype:

Clang-Tidy: Parameter 'et_const_retry' is const-qualified in the function declaration; const-qualification of parameters only has an effect in function definitions.

Arne

Acked-by on v2 1/1
#4 lore raw
In reply to Arne Schwabe
Quoted 11 lines · Arne Schwabe

Remove function event_timeout_clear_ret as it is unused.

Cleanup event_timeout_trigger a bit. Do an instant return false if the timeout is not defined and inline local_now and use event_timeout_remaining instead of local duplicated code.

Add doxygen comments for all timeout function, especially for the event_timeout_trigger function that is hard to understand otherwise.

Patch v2: add many fixes/correction suggested by Frank

The new sentences have some small issues. Gert can probably fix them on apply.

[...]

src/openvpn/interval.h event_timeout_reset(struct event_timeout *et) · line 215

Quoted 5 lines
src/openvpn/interval.h +2 -3
-/*
- * Will return the time left for a timeout, this function does not check
- * if the timeout is actually valid
+/**
+ * Returns the time until the timeout should triggered from from now.

"should be triggered, from \c now."

Quoted 34 lines

+ * This function does not check if the timeout is actually valid. */
static inline interval_t event_timeout_remaining(struct event_timeout *et)
{

src/openvpn/interval.h +13 -12
-    return (interval_t) (et->last - now + et->n);
+    return (interval_t) ((et->last + et->n) - now);
 }
 
-/*
- * This is the principal function for testing and triggering recurring
- * timers and will return true on a timer signal event.
- * If et_const_retry == ETT_DEFAULT and a signal occurs,
- * the function will return true and *et will be armed for the
- * next event.  If et_const_retry >= 0 and a signal occurs,
- * *et will not be touched, but *tv will be set to
- * minimum (*tv, et_const_retry) for a future re-test,
- * and the function will return true.
- */
-
 #define ETT_DEFAULT (-1)
 
+/**
+ * This is the principal function for testing and triggering recurring
+ * timers.
+ *
+ * If *et is not triggered, *tv is set to remaining time until the timeout if
+ * not already lower:
+ *
+ *      *tv = minimum(*tv, event_timeout_remaining(*et))
+ *
+ * If *et triggers and et_const_retry is negative (ETT_DEFAULT is -1):
+ *  - the function will return true
+ *  - *et will be armed for the next event (et->last set to now).

src/openvpn/interval.h event_timeout_reset(struct event_timeout *et) · line 247

Quoted 10 lines
src/openvpn/interval.h +10 -0
+ *  - *tv will be lowered to the event period (n) if larger than the
+ *     period of the event (set to *et's next timeout)
+ *  - *et will not changed (ie also not rearmed, stays armed)
+ *
+ * If *et triggers and et_const_retry >= 0, *tv will be lowered to et_const_try
+ * if larger:
+ *
+ *    *tv = *minimum(*tv, et_const_retry)
+ *
+ * This is mainly useful is the trigger cannot yet be triggered for other

"if the trigger"

Quoted 22 lines

+ * reasons and a backoff timeout should be returned if the timer is ready
+ * to trigger.
+ *
+ *

+ * @param et                the timeout to check
+ * @param tv                will be set to timeout for next check for this
+ *                          timeout unless already smaller.
+ * @param et_const_retry    see above
+ * @return                  if the timeout has triggered and event has been reset

+ */
bool event_timeout_trigger(struct event_timeout *et,
struct timeval *tv,

src/openvpn/interval.h +1 -1
-                           const int et_const_retry);
+                           int et_const_retry);
 
 /*
  * Measure time intervals in microseconds
src/openvpn/openvpn.h +0 -0
index 00cd652fa..95c7d7520 100644

src/openvpn/openvpn.h struct context_2 · line 391

Quoted 7 lines
src/openvpn/openvpn.h +3 -1
@@ -386,7 +386,9 @@ struct context_2
      * Event loop info
      */
 
-    /* how long to wait on link/tun read before we will need to be serviced */
+    /** Time to next event of timers and similar. This is used to determine
+     *  how long to wait on event wait (select/poll on link/tun read)
+     *  before this context wants to be serviced */

Add period for consistency.

src/openvpn/openvpn.h struct context_2 · line 394

Quoted 3 lines
src/openvpn/openvpn.h +0 -0
     struct timeval timeval;
 
     /* next wakeup for processing coarse timers (>1 sec resolution) */

Regards,

Signature · 1 line
  Frank Lichtenheld
#5 lore raw
In reply to Arne Schwabe

Thanks for the thorough review. I have adjusted the 3 minor nits in the comments, as instructed. I have also removed the spurious blank line.

The code change looks huge, indeed, unless viewed with "-w" - then it's quite straightforward. For good measure I've still subjected this to the server side torture testing, and it's all still well-behaved (= nothing new breaks).

Your patch has been applied to the master branch.

commit 0b980fa4e5761d6544ccf96b89fc2186ce23e144

Author: Arne Schwabe
Date:   Thu Oct 6 14:29:40 2022 +0200
     Document/cleanup event_timeout functions

     Signed-off-by: Arne Schwabe <[email protected]...>
     Acked-by: Frank Lichtenheld <[email protected]...>
     Message-Id: <[email protected]...>
     URL: https://www.mail-archive.com/[email protected]/msg25348.html
     Signed-off-by: Gert Doering <[email protected]...>

--
kind regards,

Gert Doering