This is an automated email from the ASF dual-hosted git repository.
jiuzhudong pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new 3538d805fc5 sched/hrtimer: refresh code comments to match
implementation
3538d805fc5 is described below
commit 3538d805fc515d0954a82211e47e24db796dd36a
Author: wangchengdong <[email protected]>
AuthorDate: Sun Jan 25 16:49:15 2026 +0800
sched/hrtimer: refresh code comments to match implementation
Several code comments in the hrtimer subsystem have become outdated
following recent implementation changes. This patch updates them to
accurately describe the current code behavior and algorithms.
Signed-off-by: Chengdong Wang <[email protected]>
---
include/nuttx/hrtimer.h | 4 ++--
sched/hrtimer/hrtimer.h | 17 +++++++++--------
sched/hrtimer/hrtimer_cancel.c | 26 +++++++++++---------------
sched/hrtimer/hrtimer_initialize.c | 23 +++++++++++++++--------
sched/hrtimer/hrtimer_process.c | 15 ++++++++-------
sched/hrtimer/hrtimer_start.c | 6 +++---
6 files changed, 48 insertions(+), 43 deletions(-)
diff --git a/include/nuttx/hrtimer.h b/include/nuttx/hrtimer.h
index a4476bf3d29..e77041f1105 100644
--- a/include/nuttx/hrtimer.h
+++ b/include/nuttx/hrtimer.h
@@ -65,7 +65,7 @@ struct hrtimer_s;
typedef CODE uint64_t (*hrtimer_entry_t)(FAR const struct hrtimer_s *hrtimer,
uint64_t expired);
-/* Red-black tree node used to order hrtimers by expiration time */
+/* Hrtimer container node used to order hrtimers by expiration time */
typedef struct hrtimer_node_s
{
@@ -85,7 +85,7 @@ typedef struct hrtimer_node_s
typedef struct hrtimer_s
{
- hrtimer_node_t node; /* RB-tree node for sorted insertion */
+ hrtimer_node_t node; /* Container node for sorted insertion */
hrtimer_entry_t func; /* Expiration callback function */
uint64_t expired; /* Absolute expiration time (ns) */
} hrtimer_t;
diff --git a/sched/hrtimer/hrtimer.h b/sched/hrtimer/hrtimer.h
index 7fec047be66..2e64624fa6a 100644
--- a/sched/hrtimer/hrtimer.h
+++ b/sched/hrtimer/hrtimer.h
@@ -52,7 +52,7 @@ RB_HEAD(hrtimer_tree_s, hrtimer_node_s);
* Public Data
****************************************************************************/
-/* Spinlock protecting access to the hrtimer RB-tree and timer state */
+/* Spinlock protecting access to the hrtimer container and timer state */
extern spinlock_t g_hrtimer_spinlock;
@@ -162,7 +162,7 @@ int hrtimer_starttimer(uint64_t ns)
*
* Description:
* Compare two high-resolution timer nodes to determine their ordering
- * in the red-black tree. Used internally by the RB-tree macros.
+ * in the container. Used internally by the RB-tree macros.
*
* Input Parameters:
* a - Pointer to the first hrtimer node.
@@ -202,7 +202,7 @@ RB_PROTOTYPE(hrtimer_tree_s, hrtimer_node_s, entry,
hrtimer_compare);
* Name: hrtimer_is_armed
*
* Description:
- * Test whether a timer is currently armed (inserted into the RB-tree).
+ * Test whether a timer is currently armed (inserted into the container).
*
* Returned Value:
* true if armed, false otherwise.
@@ -217,7 +217,7 @@ static inline_function bool hrtimer_is_armed(FAR hrtimer_t
*hrtimer)
* Name: hrtimer_remove
*
* Description:
- * Remove a timer from the RB-tree and mark it as unarmed.
+ * Remove a timer from the container and mark it as unarmed.
****************************************************************************/
static inline_function void hrtimer_remove(FAR hrtimer_t *hrtimer)
@@ -228,7 +228,7 @@ static inline_function void hrtimer_remove(FAR hrtimer_t
*hrtimer)
list_delete_fast(&hrtimer->node.entry);
#endif
- /* Explicitly clear parent to mark the timer as unarmed */
+ /* Explicitly mark the timer as unarmed */
hrtimer->func = NULL;
}
@@ -237,7 +237,8 @@ static inline_function void hrtimer_remove(FAR hrtimer_t
*hrtimer)
* Name: hrtimer_insert
*
* Description:
- * Insert a timer into the RB-tree according to its expiration time.
+ * Insert a timer into the timer container according to its
+ * expiration time.
****************************************************************************/
static inline_function void hrtimer_insert(FAR hrtimer_t *hrtimer)
@@ -286,9 +287,9 @@ static inline_function FAR hrtimer_t
*hrtimer_get_first(void)
*
* Description:
* Test whether the given high-resolution timer is the earliest
- * expiring timer in the RB-tree.
+ * expiring timer in the container.
*
- * In a red-black tree ordered by expiration time, the earliest timer
+ * In a container ordered by expiration time, the earliest timer
* is represented by the left-most node. Therefore, a timer is the
* earliest one if it has no left child.
*
diff --git a/sched/hrtimer/hrtimer_cancel.c b/sched/hrtimer/hrtimer_cancel.c
index a2b4bc6e3f7..b0b66c624b4 100644
--- a/sched/hrtimer/hrtimer_cancel.c
+++ b/sched/hrtimer/hrtimer_cancel.c
@@ -86,17 +86,15 @@ static inline_function bool hrtimer_is_active(FAR hrtimer_t
*hrtimer)
* Cancel a high-resolution timer.
*
* If the timer is currently armed, it will be removed from the active
- * hrtimer red-black tree and will not be executed.
+ * hrtimer container (tree or list) and will not be executed.
*
* If the timer callback is currently executing, the timer will be marked
- * as canceled. The running callback is allowed to complete, but the timer
+ * as canceled. The running callback is allowed to complete, but the timer
* will not be re-armed or executed again.
*
- * If the canceled timer was the earliest (head) timer in the tree, the
- * expiration of the underlying hardware timer will be updated to:
- *
- * 1. The expiration time of the next earliest timer, or
- * 2. A safe default expiration if no timers remain.
+ * If the canceled timer was the earliest (head) timer in the container,
+ * the expiration of the underlying hardware timer will be updated to the
+ * expiration time of the next earliest timer
*
* This function is non-blocking and does not wait for a running callback
* to finish.
@@ -108,8 +106,8 @@ static inline_function bool hrtimer_is_active(FAR hrtimer_t
*hrtimer)
* OK (0) on success; a negated errno value on failure.
*
* Assumptions/Notes:
- * - This function acquires the global hrtimer spinlock to protect both
- * the red-black tree and the timer state.
+ * - This function acquires the global hrtimer spinlock to protect
+ * the container.
* - The caller must ensure that the timer structure is not freed until
* it is guaranteed that any running callback has returned.
*
@@ -123,7 +121,7 @@ int hrtimer_cancel(FAR hrtimer_t *hrtimer)
DEBUGASSERT(hrtimer != NULL);
- /* Enter critical section to protect the hrtimer tree and state */
+ /* Enter critical section to protect the hrtimer container */
flags = spin_lock_irqsave(&g_hrtimer_spinlock);
@@ -162,8 +160,7 @@ int hrtimer_cancel(FAR hrtimer_t *hrtimer)
* Cancel a high-resolution timer and wait until it becomes inactive.
*
* - Calls hrtimer_cancel() to request timer cancellation.
- * - If the timer callback is running, waits until it completes and
- * the timer state transitions to HRTIMER_STATE_INACTIVE.
+ * - If the timer callback is running, waits until it completes.
* - If sleeping is allowed (normal task context), yields CPU briefly
* to avoid busy-waiting.
* - Otherwise (interrupt or idle task context), spins until completion.
@@ -190,11 +187,10 @@ int hrtimer_cancel_sync(FAR hrtimer_t *hrtimer)
return ret;
}
- /* Wait until the timer transitions to the inactive state.
+ /* Wait until all cpu finish running the timer callback.
*
* If sleeping is permitted, yield the CPU briefly to avoid
- * busy-waiting. Otherwise, spin until the callback completes
- * and the state becomes inactive.
+ * busy-waiting. Otherwise, spin until the callback completes.
*/
#ifdef CONFIG_SMP
while (hrtimer_is_active(hrtimer))
diff --git a/sched/hrtimer/hrtimer_initialize.c
b/sched/hrtimer/hrtimer_initialize.c
index 4420574f927..a79d52b8e26 100644
--- a/sched/hrtimer/hrtimer_initialize.c
+++ b/sched/hrtimer/hrtimer_initialize.c
@@ -42,24 +42,29 @@ FAR hrtimer_t *g_hrtimer_running[CONFIG_SMP_NCPUS];
/* Global spinlock protecting the high-resolution timer subsystem.
*
- * This spinlock serializes access to the hrtimer red-black tree and
+ * This spinlock serializes access to the hrtimer container and
* protects timer state transitions. It must be held whenever the
- * timer tree or hrtimer state is modified.
+ * timer container is modified.
*/
spinlock_t g_hrtimer_spinlock = SP_UNLOCKED;
-/* Red-black tree containing all active high-resolution timers.
+/* Container for all active high-resolution timers.
*
- * Only timers in the ARMED state are present in this tree. Timers in
- * the RUNNING, CANCELED, or INACTIVE states must not be inserted.
+ * When CONFIG_HRTIMER_TREE is enabled, timers are stored in a container.
+ * When disabled, timers are stored in a linked list.
*
- * The tree is ordered by absolute expiration time.
+ * The container is ordered by absolute expiration time in
+ * both configurations.
*/
#ifdef CONFIG_HRTIMER_TREE
+/* Red-black tree for hrtimer storage (requires CONFIG_HRTIMER_TREE) */
+
struct hrtimer_tree_s g_hrtimer_tree = RB_INITIALIZER(g_hrtimer_tree);
#else
+/* Linked list for hrtimer storage (fallback when tree is disabled) */
+
struct list_node g_hrtimer_list = LIST_INITIAL_VALUE(g_hrtimer_list);
#endif
@@ -71,13 +76,15 @@ struct list_node g_hrtimer_list =
LIST_INITIAL_VALUE(g_hrtimer_list);
* Name: RB_GENERATE
*
* Description:
- * Instantiate the red-black tree helper functions for the hrtimer
+ * Instantiate the container helper functions for the hrtimer
* subsystem.
*
* This macro generates the static inline functions required to
- * manipulate the hrtimer red-black tree, including insertion,
+ * manipulate the hrtimer container, including insertion,
* removal, and lookup operations.
*
+ * Note: This is only compiled when CONFIG_HRTIMER_TREE is enabled.
+ *
* Assumptions/Notes:
* - The tree key is the absolute expiration time stored in
* hrtimer_node_s and compared via hrtimer_compare().
diff --git a/sched/hrtimer/hrtimer_process.c b/sched/hrtimer/hrtimer_process.c
index c7a40fd2511..314e410d244 100644
--- a/sched/hrtimer/hrtimer_process.c
+++ b/sched/hrtimer/hrtimer_process.c
@@ -40,9 +40,10 @@
*
* Description:
* Process all expired high-resolution timers. This function repeatedly
- * retrieves the earliest timer from the active timer RB-tree, checks if it
- * has expired relative to the current time, removes it from the tree,
- * and invokes its callback function. Processing continues until:
+ * retrieves the earliest timer from the active timer container, checks
+ * if it has expired relative to the current time, removes it from the
+ * container, and invokes its callback function. Processing continues
+ * until:
*
* 1. No additional timers have expired, or
* 2. The active timer set is empty.
@@ -61,7 +62,7 @@
* None.
*
* Assumptions/Notes:
- * - This function acquires a spinlock to protect the timer RB-tree.
+ * - This function acquires a spinlock to protect the timer container.
* - Timer callbacks are invoked with interrupts enabled
* to avoid deadlocks.
* - DEBUGASSERT ensures that timer callbacks are valid.
@@ -78,7 +79,7 @@ void hrtimer_process(uint64_t now)
int cpu = this_cpu();
#endif
- /* Lock the hrtimer RB-tree to protect access */
+ /* Lock the hrtimer container to protect access */
flags = spin_lock_irqsave(&g_hrtimer_spinlock);
@@ -103,7 +104,7 @@ void hrtimer_process(uint64_t now)
break;
}
- /* Remove the expired timer from the active tree */
+ /* Remove the expired timer from the timer container */
hrtimer_remove(hrtimer);
@@ -128,7 +129,7 @@ void hrtimer_process(uint64_t now)
/* If the timer is periodic and has not been rearmed or
* cancelled concurrently,
- * compute next expiration and reinsert into RB-tree
+ * compute next expiration and reinsert into container
*/
if (period > 0 && hrtimer->expired == expired)
diff --git a/sched/hrtimer/hrtimer_start.c b/sched/hrtimer/hrtimer_start.c
index 0f24e0952c9..ca35a62422f 100644
--- a/sched/hrtimer/hrtimer_start.c
+++ b/sched/hrtimer/hrtimer_start.c
@@ -54,7 +54,7 @@
*
* Assumptions/Notes:
* - This function disables interrupts briefly via spinlock to safely
- * insert the timer into the RB-tree.
+ * insert the timer into the container.
* - Absolute mode sets the timer to expire at the given absolute time.
* - Relative mode sets the timer to expire after 'ns'
* nanoseconds from the current time.
@@ -69,7 +69,7 @@ int hrtimer_start(FAR hrtimer_t *hrtimer, hrtimer_entry_t
func,
DEBUGASSERT(hrtimer != NULL);
- /* Protect RB-tree manipulation with spinlock and disable interrupts */
+ /* Protect container manipulation with spinlock and disable interrupts */
flags = spin_lock_irqsave(&g_hrtimer_spinlock);
@@ -95,7 +95,7 @@ int hrtimer_start(FAR hrtimer_t *hrtimer, hrtimer_entry_t
func,
DEBUGASSERT(hrtimer->expired >= expired);
- /* Insert the timer into the RB-tree */
+ /* Insert the timer into the container */
hrtimer_insert(hrtimer);
