Skip to contentSkip to conversation

rust: hrtimer: document handle based design rationale

PATCH In review Andreas Hindborg 4 participants 6 messages Feb 15 – Feb 28

Subsystems (2)
lore
Share & tools
lore

Andreas Hindborg

author maintainer
#0 lore raw

PATCH 1/1 rust: hrtimer: document handle based design rationale

Add implementation notes explaining why the hrtimer abstraction uses a handle based approach.

---
 rust/kernel/time/hrtimer.rs | 12 ++++++++++++
 1 file changed, 12 insertions(+)
rust/kernel/time/hrtimer.rs +12 -0
index 856d2d929a008..f92880b2cbdbd 100644
@@ -67,6 +67,18 @@
 //! A `restart` operation on a timer in the **stopped** state is equivalent to a
 //! `start` operation.
 
+// Implementation details
+//
+// The reasoning for adopting a handle based approach:
+// - If we explicitly drop the target of a timer callback in the timer callback, we
+//   may get a dangling reference.
+// - If the callback owns the last reference to the target, target may be dropped
+//   in non-sleepable context when the callback is finished.
+// - When dropping an object that is the target of an armed timer, we may drop
+//   fields accessed by the timer callback before we cancel the timer (drop order).
+//
+// By using a handle, we can make the handle own the callback target and avoid these problems.
+
 use super::{ClockSource, Delta, Instant};
 use crate::{prelude::*, types::Opaque};
 use core::{marker::PhantomData, ptr::NonNull};

---
base-commit: 05f7e89ab9731565d8a62e3b5d1ec206485eeb0b
change-id: 20260215-hrtimer-docs-52ec9c020285

Best regards,

Signature · 1 line
Andreas Hindborg <[email protected]>
reviewer Reviewed-by on v1 1/1
#2 lore raw
In reply to Andreas Hindborg
Quoted 4 lines · Andreas Hindborg

Add implementation notes explaining why the hrtimer abstraction uses a handle based approach.

Thanks for adding this!

However I feel these are not just implementation details. They are the design decision we made because of the limitation you mentioned. Maybe make them "//!" doc comment and just put them as a separate section that describes the necessity of handles? Thoughts?

Regards,
Boqun

Quoted 40 lines
---
 rust/kernel/time/hrtimer.rs | 12 ++++++++++++
 1 file changed, 12 insertions(+)
rust/kernel/time/hrtimer.rs +12 -0
index 856d2d929a008..f92880b2cbdbd 100644
@@ -67,6 +67,18 @@
 //! A `restart` operation on a timer in the **stopped** state is equivalent to a
 //! `start` operation.
 
+// Implementation details
 
 
 
+//
+// The reasoning for adopting a handle based approach:
+// - If we explicitly drop the target of a timer callback in the timer callback, we
+//   may get a dangling reference.
+// - If the callback owns the last reference to the target, target may be dropped
+//   in non-sleepable context when the callback is finished.
+// - When dropping an object that is the target of an armed timer, we may drop
+//   fields accessed by the timer callback before we cancel the timer (drop order).
+//
+// By using a handle, we can make the handle own the callback target and avoid these problems.
+

use super::{ClockSource, Delta, Instant};
use crate::{prelude::*, types::Opaque};
use core::{marker::PhantomData, ptr::NonNull};

---
base-commit: 05f7e89ab9731565d8a62e3b5d1ec206485eeb0b
change-id: 20260215-hrtimer-docs-52ec9c020285

Best regards,

Signature · 1 line
Andreas Hindborg <[email protected]>
author maintainer
#3 lore raw
Quoted 6 lines · Boqun Feng
Quoted 4 lines · Andreas Hindborg

Add implementation notes explaining why the hrtimer abstraction uses a handle based approach.

Quoted 8 lines

Thanks for adding this!

However I feel these are not just implementation details. They are the design decision we made because of the limitation you mentioned. Maybe make them "//!" doc comment and just put them as a separate section that describes the necessity of handles? Thoughts?

I don't think these details are important for the reader of the API? If you just want to use a timer, this is not something you want to read through.

Best regards,
Andreas Hindborg

reviewer
#4 lore raw
Quoted 12 lines · Andreas Hindborg
Quoted 10 lines · Boqun Feng
Quoted 4 lines · Andreas Hindborg

Add implementation notes explaining why the hrtimer abstraction uses a handle based approach.

Thanks for adding this!

Quoted 9 lines
Quoted 4 lines

However I feel these are not just implementation details. They are the design decision we made because of the limitation you mentioned. Maybe make them "//!" doc comment and just put them as a separate section that describes the necessity of handles? Thoughts?

I don't think these details are important for the reader of the API? If you just want to use a timer, this is not something you want to read through.

Fair enough ;-)

Regards,
Boqun

Quoted 6 lines

Best regards,
Andreas Hindborg

Reviewed-by on v1 1/1
#5 lore raw
In reply to Andreas Hindborg
Quoted 18 lines · On Sun, 15 Feb 2026 21:36:04 +0100 Andreas Hindborg <[email protected]>…

Add implementation notes explaining why the hrtimer abstraction uses a handle based approach.

---
 rust/kernel/time/hrtimer.rs | 12 ++++++++++++
 1 file changed, 12 insertions(+)
rust/kernel/time/hrtimer.rs +2 -0
index 856d2d929a008..f92880b2cbdbd 100644
@@ -67,6 +67,18 @@
 //! A `restart` operation on a timer in the **stopped** state is equivalent to a
 //! `start` operation.
 
+// Implementation details
+//

rust/kernel/time/hrtimer.rs line 81

Quoted 10 lines
rust/kernel/time/hrtimer.rs +10 -0
+// The reasoning for adopting a handle based approach:
+// - If we explicitly drop the target of a timer callback in the timer callback, we
+//   may get a dangling reference.
+// - If the callback owns the last reference to the target, target may be dropped
+//   in non-sleepable context when the callback is finished.
+// - When dropping an object that is the target of an armed timer, we may drop
+//   fields accessed by the timer callback before we cancel the timer (drop order).
+//
+// By using a handle, we can make the handle own the callback target and avoid these problems.
+