From: Frank Lichtenheld Date: Mon, 15 Dec 2025 14:46:50 +0000 (+0100) Subject: schedule: Rework documentation for schedule_add_entry X-Git-Tag: v2.7_rc4~8 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=223192a092eacda12ee1ac93fd017bd43fb60f01;p=thirdparty%2Fopenvpn.git schedule: Rework documentation for schedule_add_entry The previous documentation was very misleading and made it hard to understand how the sigma parameter is used. Rewrite it so that it better reflects the actual implementation. Change-Id: Idd79f7cbd38e8b0831f15866339c3677a367cd49 Signed-off-by: Frank Lichtenheld Acked-by: Gert Doering Gerrit URL: https://gerrit.openvpn.net/c/openvpn/+/1439 Message-Id: <20251215144656.17299-1-gert@greenie.muc.de> URL: https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg35070.html Signed-off-by: Gert Doering --- diff --git a/src/openvpn/schedule.h b/src/openvpn/schedule.h index 79311c546..3e2a2adaf 100644 --- a/src/openvpn/schedule.h +++ b/src/openvpn/schedule.h @@ -81,17 +81,26 @@ void schedule_remove_node(struct schedule *s, struct schedule_entry *e); /* Public inline functions */ -/* - * Add a struct schedule_entry (whose storage is managed by - * caller) to the btree. tv signifies the wakeup time for - * a future event. sigma is a time interval measured - * in microseconds -- the event window being represented - * starts at (tv - sigma) and ends at (tv + sigma). - * Event signaling can occur anywere within this interval. - * Making the interval larger makes the scheduler more efficient, - * while making it smaller results in more precise scheduling. - * The caller should treat the passed struct schedule_entry as - * an opaque object. +/** + * Add a struct schedule_entry to the scheduler btree or + * update an existing entry with a new wakeup time. + * + * @p sigma is only used when the entry is already present + * in the schedule. If the originally scheduled time and the new + * time are within @p sigma microseconds of each other then the + * entry is not rescheduled and will occur at the original time. + * When adding a new entry @p sigma will be ignored. + * + * @param s scheduler tree + * @param e entry to add to the schedule + * @param tv wakeup time for the entry + * @param sigma window size for the event in microseconds + * + * @note The caller should treat @p e as opaque data. Only + * the scheduler functions should change the object. The + * caller is expected to manage the memory for the object + * and must only free it once it has been removed from the + * schedule. */ static inline void schedule_add_entry(struct schedule *s, struct schedule_entry *e, const struct timeval *tv,