Document/cleanup event_timeout functions
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
@@ -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
@@ -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)
Quoted 5 lines · Arne Schwabe
Remove function
event_timeout_clear_retas it is unused.Cleanup
event_timeout_triggera bit. Do an instant return false if the timeout is not defined and inlinelocal_nowand useevent_timeout_remaininginstead 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_triggerfunction that is hard to understand otherwise.
Some comments on those below.
Quoted 35 lines
src/openvpn/interval.h +9
-4@@ -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
-12static 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
-1bool 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@@ -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
-0struct 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
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
PATCH v2 1/1 Document/cleanup event_timeout functions
In reply to Arne SchwabeRemove 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
@@ -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
@@ -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)
Quoted 11 lines · Arne Schwabe
Remove function
event_timeout_clear_retas it is unused.Cleanup
event_timeout_triggera bit. Do an instant return false if the timeout is not defined and inlinelocal_nowand useevent_timeout_remaininginstead of local duplicated code.Add doxygen comments for all timeout function, especially for the
event_timeout_triggerfunction 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 inlineinterval_tevent_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(structevent_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
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
-0struct timeval timeval;/* next wakeup for processing coarse timers (>1 sec resolution) */
Regards,
Signature · 1 line
Frank Lichtenheld
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