rust: hrtimer: document handle based design rationale
Subsystems (2)
Andreas Hindborg
maintainerPATCH 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
@@ -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]>
Quoted 4 lines · Andreas Hindborg
Add implementation notes explaining why the hrtimer abstraction uses a handle based approach.
Signed-off-by Andreas Hindborg <[email protected]>
Quoted 4 lines · Andreas Hindborg
Add implementation notes explaining why the hrtimer abstraction uses a handle based approach.
Signed-off-by Andreas Hindborg <[email protected]>
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@@ -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-52ec9c020285Best regards,
Signature · 1 line
Andreas Hindborg <[email protected]>
Andreas Hindborg
maintainerQuoted 6 lines · Boqun Feng
Quoted 4 lines · Andreas Hindborg
Add implementation notes explaining why the hrtimer abstraction uses a handle based approach.
Signed-off-by Andreas Hindborg <[email protected]>
Quoted 8 lines
Thanks for adding this!
Reviewed-by Boqun Feng <[email protected]>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
Boqun Feng
reviewerQuoted 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.
Signed-off-by Andreas Hindborg <[email protected]>Thanks for adding this!
Reviewed-by Boqun Feng <[email protected]>
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
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.
Signed-off-by Andreas Hindborg <[email protected]>--- rust/kernel/time/hrtimer.rs | 12 ++++++++++++ 1 file changed, 12 insertions(+)rust/kernel/time/hrtimer.rs +2
-0@@ -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. +