rust: hrtimer: document handle based design rationale

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

Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Reviewed-by: Boqun Feng <boqun@kernel.org>
Reviewed-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
Link: https://msgid.link/20260215-hrtimer-docs-v1-1-bff6a6c0d923@kernel.org
Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>

1 files changed, 11 insertions, 0 deletions

diff --git a/rust/kernel/time/hrtimer.rs b/rust/kernel/time/hrtimer.rs
index 87aafbee0ce9..c0180b8ca5d3 100644
--- a/rust/kernel/time/hrtimer.rs
+++ b/rust/kernel/time/hrtimer.rs
@@ -402,6 +402,17 @@
 //! ```
 //!
 //! [`Arc`]: kernel::sync::Arc
+// 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::{ClockId, Delta, Instant};
 use crate::{prelude::*, types::Opaque};