* [PATCH v2] hrtimer: add usage examples to documentation
@ 2026-02-19 11:57 Andreas Hindborg
2026-02-19 12:31 ` Alice Ryhl
2026-03-23 11:07 ` Andreas Hindborg
0 siblings, 2 replies; 5+ messages in thread
From: Andreas Hindborg @ 2026-02-19 11:57 UTC (permalink / raw)
To: Andreas Hindborg, Boqun Feng, FUJITA Tomonori,
Frederic Weisbecker, Lyude Paul, Thomas Gleixner,
Anna-Maria Behnsen, John Stultz, Stephen Boyd, Miguel Ojeda,
Gary Guo, Björn Roy Baron, Benno Lossin, Alice Ryhl,
Trevor Gross, Danilo Krummrich
Cc: rust-for-linux, linux-kernel, Daniel Almeida
Add documentation examples showing various ways to use hrtimers:
- Box-allocated timers with shared state in Arc.
- Arc-allocated timers.
- Stack-based timers for scoped usage.
- Mutable stack-based timers with shared state.
Tested-by: Daniel Almeida <daniel.almeida@collabora.com>
Reviewed-by: Daniel Almeida <daniel.almeida@collabora.com>
Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
---
Changes in v2:
- Sprinkle blank lines for readability
- Change heading for Arc example
- Fix error handling.
- Link to v1: https://lore.kernel.org/r/20251217-hrtimer-examples-v6-19-rc1-v1-1-4ad0e7e4c4e0@kernel.org
---
rust/kernel/time/hrtimer.rs | 336 ++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 336 insertions(+)
diff --git a/rust/kernel/time/hrtimer.rs b/rust/kernel/time/hrtimer.rs
index 856d2d929a008..2d7f1131a8131 100644
--- a/rust/kernel/time/hrtimer.rs
+++ b/rust/kernel/time/hrtimer.rs
@@ -66,6 +66,342 @@
//!
//! A `restart` operation on a timer in the **stopped** state is equivalent to a
//! `start` operation.
+//!
+//! When a type implements both `HrTimerPointer` and `Clone`, it is possible to
+//! issue the `start` operation while the timer is in the **started** state. In
+//! this case the `start` operation is equivalent to the `restart` operation.
+//!
+//! # Examples
+//!
+//! ## Using an intrusive timer living in a [`Box`]
+//!
+//! ```
+//! # use kernel::{
+//! # alloc::flags,
+//! # impl_has_hr_timer,
+//! # prelude::*,
+//! # sync::{
+//! # atomic::{ordering, Atomic},
+//! # completion::Completion,
+//! # Arc,
+//! # },
+//! # time::{
+//! # hrtimer::{
+//! # RelativeMode, HrTimer, HrTimerCallback, HrTimerPointer,
+//! # HrTimerRestart, HrTimerCallbackContext
+//! # },
+//! # Delta, Monotonic,
+//! # },
+//! # };
+//!
+//! #[pin_data]
+//! struct Shared {
+//! #[pin]
+//! flag: Atomic<u64>,
+//! #[pin]
+//! cond: Completion,
+//! }
+//!
+//! impl Shared {
+//! fn new() -> impl PinInit<Self> {
+//! pin_init!(Self {
+//! flag <- Atomic::new(0),
+//! cond <- Completion::new(),
+//! })
+//! }
+//! }
+//!
+//! #[pin_data]
+//! struct BoxIntrusiveHrTimer {
+//! #[pin]
+//! timer: HrTimer<Self>,
+//! shared: Arc<Shared>,
+//! }
+//!
+//! impl BoxIntrusiveHrTimer {
+//! fn new() -> impl PinInit<Self, kernel::error::Error> {
+//! try_pin_init!(Self {
+//! timer <- HrTimer::new(),
+//! shared: Arc::pin_init(Shared::new(), flags::GFP_KERNEL)?,
+//! })
+//! }
+//! }
+//!
+//! impl HrTimerCallback for BoxIntrusiveHrTimer {
+//! type Pointer<'a> = Pin<KBox<Self>>;
+//!
+//! fn run(this: Pin<&mut Self>, _ctx: HrTimerCallbackContext<'_, Self>) -> HrTimerRestart {
+//! pr_info!("Timer called\n");
+//!
+//! let flag = this.shared.flag.fetch_add(1, ordering::Full);
+//! this.shared.cond.complete_all();
+//!
+//! if flag == 4 {
+//! HrTimerRestart::NoRestart
+//! } else {
+//! HrTimerRestart::Restart
+//! }
+//! }
+//! }
+//!
+//! impl_has_hr_timer! {
+//! impl HasHrTimer<Self> for BoxIntrusiveHrTimer {
+//! mode: RelativeMode<Monotonic>, field: self.timer
+//! }
+//! }
+//!
+//! let has_timer = Box::pin_init(BoxIntrusiveHrTimer::new(), GFP_KERNEL)?;
+//! let shared = has_timer.shared.clone();
+//! let _handle = has_timer.start(Delta::from_micros(200));
+//!
+//! while shared.flag.load(ordering::Relaxed) != 5 {
+//! shared.cond.wait_for_completion();
+//! }
+//!
+//! pr_info!("Counted to 5\n");
+//! # Ok::<(), kernel::error::Error>(())
+//! ```
+//!
+//! ## Using an intrusive timer in an [`Arc`]
+//!
+//! ```
+//! # use kernel::{
+//! # alloc::flags,
+//! # impl_has_hr_timer,
+//! # prelude::*,
+//! # sync::{
+//! # atomic::{ordering, Atomic},
+//! # completion::Completion,
+//! # Arc, ArcBorrow,
+//! # },
+//! # time::{
+//! # hrtimer::{
+//! # RelativeMode, HrTimer, HrTimerCallback, HrTimerPointer, HrTimerRestart,
+//! # HasHrTimer, HrTimerCallbackContext
+//! # },
+//! # Delta, Monotonic,
+//! # },
+//! # };
+//!
+//! #[pin_data]
+//! struct ArcIntrusiveHrTimer {
+//! #[pin]
+//! timer: HrTimer<Self>,
+//! #[pin]
+//! flag: Atomic<u64>,
+//! #[pin]
+//! cond: Completion,
+//! }
+//!
+//! impl ArcIntrusiveHrTimer {
+//! fn new() -> impl PinInit<Self> {
+//! pin_init!(Self {
+//! timer <- HrTimer::new(),
+//! flag <- Atomic::new(0),
+//! cond <- Completion::new(),
+//! })
+//! }
+//! }
+//!
+//! impl HrTimerCallback for ArcIntrusiveHrTimer {
+//! type Pointer<'a> = Arc<Self>;
+//!
+//! fn run(
+//! this: ArcBorrow<'_, Self>,
+//! _ctx: HrTimerCallbackContext<'_, Self>,
+//! ) -> HrTimerRestart {
+//! pr_info!("Timer called\n");
+//!
+//! let flag = this.flag.fetch_add(1, ordering::Full);
+//! this.cond.complete_all();
+//!
+//! if flag == 4 {
+//! HrTimerRestart::NoRestart
+//! } else {
+//! HrTimerRestart::Restart
+//! }
+//! }
+//! }
+//!
+//! impl_has_hr_timer! {
+//! impl HasHrTimer<Self> for ArcIntrusiveHrTimer {
+//! mode: RelativeMode<Monotonic>, field: self.timer
+//! }
+//! }
+//!
+//! let has_timer = Arc::pin_init(ArcIntrusiveHrTimer::new(), GFP_KERNEL)?;
+//! let _handle = has_timer.clone().start(Delta::from_micros(200));
+//!
+//! while has_timer.flag.load(ordering::Relaxed) != 5 {
+//! has_timer.cond.wait_for_completion();
+//! }
+//!
+//! pr_info!("Counted to 5\n");
+//! # Ok::<(), kernel::error::Error>(())
+//! ```
+//!
+//! ## Using a stack-based timer
+//!
+//! ```
+//! # use kernel::{
+//! # impl_has_hr_timer,
+//! # prelude::*,
+//! # sync::{
+//! # atomic::{ordering, Atomic},
+//! # completion::Completion,
+//! # },
+//! # time::{
+//! # hrtimer::{
+//! # ScopedHrTimerPointer, HrTimer, HrTimerCallback, HrTimerPointer, HrTimerRestart,
+//! # HasHrTimer, RelativeMode, HrTimerCallbackContext
+//! # },
+//! # Delta, Monotonic,
+//! # },
+//! # };
+//! # use pin_init::stack_pin_init;
+//!
+//! #[pin_data]
+//! struct IntrusiveHrTimer {
+//! #[pin]
+//! timer: HrTimer<Self>,
+//! #[pin]
+//! flag: Atomic<u64>,
+//! #[pin]
+//! cond: Completion,
+//! }
+//!
+//! impl IntrusiveHrTimer {
+//! fn new() -> impl PinInit<Self> {
+//! pin_init!(Self {
+//! timer <- HrTimer::new(),
+//! flag <- Atomic::new(0),
+//! cond <- Completion::new(),
+//! })
+//! }
+//! }
+//!
+//! impl HrTimerCallback for IntrusiveHrTimer {
+//! type Pointer<'a> = Pin<&'a Self>;
+//!
+//! fn run(this: Pin<&Self>, _ctx: HrTimerCallbackContext<'_, Self>) -> HrTimerRestart {
+//! pr_info!("Timer called\n");
+//!
+//! this.flag.store(1, ordering::Release);
+//! this.cond.complete_all();
+//!
+//! HrTimerRestart::NoRestart
+//! }
+//! }
+//!
+//! impl_has_hr_timer! {
+//! impl HasHrTimer<Self> for IntrusiveHrTimer {
+//! mode: RelativeMode<Monotonic>, field: self.timer
+//! }
+//! }
+//!
+//! stack_pin_init!( let has_timer = IntrusiveHrTimer::new() );
+//! has_timer.as_ref().start_scoped(Delta::from_micros(200), || {
+//! while has_timer.flag.load(ordering::Relaxed) != 1 {
+//! has_timer.cond.wait_for_completion();
+//! }
+//! });
+//!
+//! pr_info!("Flag raised\n");
+//! # Ok::<(), kernel::error::Error>(())
+//! ```
+//!
+//! ## Using a mutable stack-based timer
+//!
+//! ```
+//! # use kernel::{
+//! # alloc::flags,
+//! # impl_has_hr_timer,
+//! # prelude::*,
+//! # sync::{
+//! # atomic::{ordering, Atomic},
+//! # completion::Completion,
+//! # Arc,
+//! # },
+//! # time::{
+//! # hrtimer::{
+//! # ScopedHrTimerPointer, HrTimer, HrTimerCallback, HrTimerPointer, HrTimerRestart,
+//! # HasHrTimer, RelativeMode, HrTimerCallbackContext
+//! # },
+//! # Delta, Monotonic,
+//! # },
+//! # };
+//! # use pin_init::stack_try_pin_init;
+//!
+//! #[pin_data]
+//! struct Shared {
+//! #[pin]
+//! flag: Atomic<u64>,
+//! #[pin]
+//! cond: Completion,
+//! }
+//!
+//! impl Shared {
+//! fn new() -> impl PinInit<Self> {
+//! pin_init!(Self {
+//! flag <- Atomic::new(0),
+//! cond <- Completion::new(),
+//! })
+//! }
+//! }
+//!
+//! #[pin_data]
+//! struct IntrusiveHrTimer {
+//! #[pin]
+//! timer: HrTimer<Self>,
+//! shared: Arc<Shared>,
+//! }
+//!
+//! impl IntrusiveHrTimer {
+//! fn new() -> impl PinInit<Self, kernel::error::Error> {
+//! try_pin_init!(Self {
+//! timer <- HrTimer::new(),
+//! shared: Arc::pin_init(Shared::new(), flags::GFP_KERNEL)?,
+//! })
+//! }
+//! }
+//!
+//! impl HrTimerCallback for IntrusiveHrTimer {
+//! type Pointer<'a> = Pin<&'a mut Self>;
+//!
+//! fn run(this: Pin<&mut Self>, _ctx: HrTimerCallbackContext<'_, Self>) -> HrTimerRestart {
+//! pr_info!("Timer called\n");
+//!
+//! let flag = this.shared.flag.fetch_add(1, ordering::Full);
+//! this.shared.cond.complete_all();
+//!
+//! if flag == 4 {
+//! HrTimerRestart::NoRestart
+//! } else {
+//! HrTimerRestart::Restart
+//! }
+//! }
+//! }
+//!
+//! impl_has_hr_timer! {
+//! impl HasHrTimer<Self> for IntrusiveHrTimer {
+//! mode: RelativeMode<Monotonic>, field: self.timer
+//! }
+//! }
+//!
+//! stack_try_pin_init!( let has_timer =? IntrusiveHrTimer::new() );
+//! let shared = has_timer.shared.clone();
+//!
+//! has_timer.as_mut().start_scoped(Delta::from_micros(200), || {
+//! while shared.flag.load(ordering::Relaxed) != 5 {
+//! shared.cond.wait_for_completion();
+//! }
+//! });
+//!
+//! pr_info!("Counted to 5\n");
+//! # Ok::<(), kernel::error::Error>(())
+//! ```
+//!
+//! [`Arc`]: kernel::sync::Arc
use super::{ClockSource, Delta, Instant};
use crate::{prelude::*, types::Opaque};
---
base-commit: 8f0b4cce4481fb22653697cced8d0d04027cb1e8
change-id: 20251215-hrtimer-examples-v6-19-rc1-2658ce9bb5d0
Best regards,
--
Andreas Hindborg <a.hindborg@kernel.org>
^ permalink raw reply related [flat|nested] 5+ messages in thread* Re: [PATCH v2] hrtimer: add usage examples to documentation
2026-02-19 11:57 [PATCH v2] hrtimer: add usage examples to documentation Andreas Hindborg
@ 2026-02-19 12:31 ` Alice Ryhl
2026-02-19 13:35 ` Andreas Hindborg
2026-03-23 11:07 ` Andreas Hindborg
1 sibling, 1 reply; 5+ messages in thread
From: Alice Ryhl @ 2026-02-19 12:31 UTC (permalink / raw)
To: Andreas Hindborg
Cc: Boqun Feng, FUJITA Tomonori, Frederic Weisbecker, Lyude Paul,
Thomas Gleixner, Anna-Maria Behnsen, John Stultz, Stephen Boyd,
Miguel Ojeda, Gary Guo, Björn Roy Baron, Benno Lossin,
Trevor Gross, Danilo Krummrich, rust-for-linux, linux-kernel,
Daniel Almeida
On Thu, Feb 19, 2026 at 12:57:45PM +0100, Andreas Hindborg wrote:
> Add documentation examples showing various ways to use hrtimers:
>
> - Box-allocated timers with shared state in Arc.
> - Arc-allocated timers.
> - Stack-based timers for scoped usage.
> - Mutable stack-based timers with shared state.
>
> Tested-by: Daniel Almeida <daniel.almeida@collabora.com>
> Reviewed-by: Daniel Almeida <daniel.almeida@collabora.com>
> Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
> ---
> Changes in v2:
> - Sprinkle blank lines for readability
> - Change heading for Arc example
> - Fix error handling.
> - Link to v1: https://lore.kernel.org/r/20251217-hrtimer-examples-v6-19-rc1-v1-1-4ad0e7e4c4e0@kernel.org
> ---
> rust/kernel/time/hrtimer.rs | 336 ++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 336 insertions(+)
>
> diff --git a/rust/kernel/time/hrtimer.rs b/rust/kernel/time/hrtimer.rs
> index 856d2d929a008..2d7f1131a8131 100644
> --- a/rust/kernel/time/hrtimer.rs
> +++ b/rust/kernel/time/hrtimer.rs
> @@ -66,6 +66,342 @@
> //!
> //! A `restart` operation on a timer in the **stopped** state is equivalent to a
> //! `start` operation.
> +//!
> +//! When a type implements both `HrTimerPointer` and `Clone`, it is possible to
> +//! issue the `start` operation while the timer is in the **started** state. In
> +//! this case the `start` operation is equivalent to the `restart` operation.
> +//!
> +//! # Examples
> +//!
> +//! ## Using an intrusive timer living in a [`Box`]
> +//!
> +//! ```
> +//! # use kernel::{
> +//! # alloc::flags,
> +//! # impl_has_hr_timer,
> +//! # prelude::*,
> +//! # sync::{
> +//! # atomic::{ordering, Atomic},
> +//! # completion::Completion,
> +//! # Arc,
> +//! # },
> +//! # time::{
> +//! # hrtimer::{
> +//! # RelativeMode, HrTimer, HrTimerCallback, HrTimerPointer,
> +//! # HrTimerRestart, HrTimerCallbackContext
> +//! # },
> +//! # Delta, Monotonic,
> +//! # },
> +//! # };
> +//!
Either do not hide the imports, or remove this empty newline.
> +//! #[pin_data]
> +//! struct Shared {
> +//! #[pin]
> +//! flag: Atomic<u64>,
> +//! #[pin]
> +//! cond: Completion,
> +//! }
> +//!
> +//! impl Shared {
> +//! fn new() -> impl PinInit<Self> {
> +//! pin_init!(Self {
> +//! flag <- Atomic::new(0),
> +//! cond <- Completion::new(),
> +//! })
> +//! }
> +//! }
> +//!
> +//! #[pin_data]
> +//! struct BoxIntrusiveHrTimer {
> +//! #[pin]
> +//! timer: HrTimer<Self>,
> +//! shared: Arc<Shared>,
> +//! }
> +//!
> +//! impl BoxIntrusiveHrTimer {
> +//! fn new() -> impl PinInit<Self, kernel::error::Error> {
> +//! try_pin_init!(Self {
> +//! timer <- HrTimer::new(),
> +//! shared: Arc::pin_init(Shared::new(), flags::GFP_KERNEL)?,
> +//! })
> +//! }
> +//! }
> +//!
> +//! impl HrTimerCallback for BoxIntrusiveHrTimer {
> +//! type Pointer<'a> = Pin<KBox<Self>>;
> +//!
> +//! fn run(this: Pin<&mut Self>, _ctx: HrTimerCallbackContext<'_, Self>) -> HrTimerRestart {
> +//! pr_info!("Timer called\n");
> +//!
> +//! let flag = this.shared.flag.fetch_add(1, ordering::Full);
> +//! this.shared.cond.complete_all();
> +//!
> +//! if flag == 4 {
> +//! HrTimerRestart::NoRestart
> +//! } else {
> +//! HrTimerRestart::Restart
> +//! }
> +//! }
> +//! }
> +//!
> +//! impl_has_hr_timer! {
> +//! impl HasHrTimer<Self> for BoxIntrusiveHrTimer {
> +//! mode: RelativeMode<Monotonic>, field: self.timer
> +//! }
> +//! }
> +//!
> +//! let has_timer = Box::pin_init(BoxIntrusiveHrTimer::new(), GFP_KERNEL)?;
> +//! let shared = has_timer.shared.clone();
> +//! let _handle = has_timer.start(Delta::from_micros(200));
> +//!
> +//! while shared.flag.load(ordering::Relaxed) != 5 {
> +//! shared.cond.wait_for_completion();
> +//! }
> +//!
> +//! pr_info!("Counted to 5\n");
> +//! # Ok::<(), kernel::error::Error>(())
> +//! ```
> +//!
> +//! ## Using an intrusive timer in an [`Arc`]
> +//!
> +//! ```
> +//! # use kernel::{
> +//! # alloc::flags,
> +//! # impl_has_hr_timer,
> +//! # prelude::*,
> +//! # sync::{
> +//! # atomic::{ordering, Atomic},
> +//! # completion::Completion,
> +//! # Arc, ArcBorrow,
> +//! # },
> +//! # time::{
> +//! # hrtimer::{
> +//! # RelativeMode, HrTimer, HrTimerCallback, HrTimerPointer, HrTimerRestart,
> +//! # HasHrTimer, HrTimerCallbackContext
> +//! # },
> +//! # Delta, Monotonic,
> +//! # },
> +//! # };
> +//!
Ditto.
> +//! #[pin_data]
> +//! struct ArcIntrusiveHrTimer {
> +//! #[pin]
> +//! timer: HrTimer<Self>,
> +//! #[pin]
> +//! flag: Atomic<u64>,
> +//! #[pin]
> +//! cond: Completion,
> +//! }
> +//!
> +//! impl ArcIntrusiveHrTimer {
> +//! fn new() -> impl PinInit<Self> {
> +//! pin_init!(Self {
> +//! timer <- HrTimer::new(),
> +//! flag <- Atomic::new(0),
> +//! cond <- Completion::new(),
> +//! })
> +//! }
> +//! }
> +//!
> +//! impl HrTimerCallback for ArcIntrusiveHrTimer {
> +//! type Pointer<'a> = Arc<Self>;
> +//!
> +//! fn run(
> +//! this: ArcBorrow<'_, Self>,
> +//! _ctx: HrTimerCallbackContext<'_, Self>,
> +//! ) -> HrTimerRestart {
> +//! pr_info!("Timer called\n");
> +//!
> +//! let flag = this.flag.fetch_add(1, ordering::Full);
> +//! this.cond.complete_all();
> +//!
> +//! if flag == 4 {
> +//! HrTimerRestart::NoRestart
> +//! } else {
> +//! HrTimerRestart::Restart
> +//! }
> +//! }
> +//! }
> +//!
> +//! impl_has_hr_timer! {
> +//! impl HasHrTimer<Self> for ArcIntrusiveHrTimer {
> +//! mode: RelativeMode<Monotonic>, field: self.timer
> +//! }
> +//! }
> +//!
> +//! let has_timer = Arc::pin_init(ArcIntrusiveHrTimer::new(), GFP_KERNEL)?;
> +//! let _handle = has_timer.clone().start(Delta::from_micros(200));
> +//!
> +//! while has_timer.flag.load(ordering::Relaxed) != 5 {
> +//! has_timer.cond.wait_for_completion();
> +//! }
> +//!
> +//! pr_info!("Counted to 5\n");
> +//! # Ok::<(), kernel::error::Error>(())
> +//! ```
> +//!
> +//! ## Using a stack-based timer
> +//!
> +//! ```
> +//! # use kernel::{
> +//! # impl_has_hr_timer,
> +//! # prelude::*,
> +//! # sync::{
> +//! # atomic::{ordering, Atomic},
> +//! # completion::Completion,
> +//! # },
> +//! # time::{
> +//! # hrtimer::{
> +//! # ScopedHrTimerPointer, HrTimer, HrTimerCallback, HrTimerPointer, HrTimerRestart,
> +//! # HasHrTimer, RelativeMode, HrTimerCallbackContext
> +//! # },
> +//! # Delta, Monotonic,
> +//! # },
> +//! # };
> +//! # use pin_init::stack_pin_init;
> +//!
Ditto.
> +//! #[pin_data]
> +//! struct IntrusiveHrTimer {
> +//! #[pin]
> +//! timer: HrTimer<Self>,
> +//! #[pin]
> +//! flag: Atomic<u64>,
> +//! #[pin]
> +//! cond: Completion,
> +//! }
> +//!
> +//! impl IntrusiveHrTimer {
> +//! fn new() -> impl PinInit<Self> {
> +//! pin_init!(Self {
> +//! timer <- HrTimer::new(),
> +//! flag <- Atomic::new(0),
> +//! cond <- Completion::new(),
> +//! })
> +//! }
> +//! }
> +//!
> +//! impl HrTimerCallback for IntrusiveHrTimer {
> +//! type Pointer<'a> = Pin<&'a Self>;
> +//!
> +//! fn run(this: Pin<&Self>, _ctx: HrTimerCallbackContext<'_, Self>) -> HrTimerRestart {
> +//! pr_info!("Timer called\n");
> +//!
> +//! this.flag.store(1, ordering::Release);
> +//! this.cond.complete_all();
> +//!
> +//! HrTimerRestart::NoRestart
> +//! }
> +//! }
> +//!
> +//! impl_has_hr_timer! {
> +//! impl HasHrTimer<Self> for IntrusiveHrTimer {
> +//! mode: RelativeMode<Monotonic>, field: self.timer
> +//! }
> +//! }
> +//!
> +//! stack_pin_init!( let has_timer = IntrusiveHrTimer::new() );
> +//! has_timer.as_ref().start_scoped(Delta::from_micros(200), || {
> +//! while has_timer.flag.load(ordering::Relaxed) != 1 {
> +//! has_timer.cond.wait_for_completion();
> +//! }
> +//! });
> +//!
> +//! pr_info!("Flag raised\n");
> +//! # Ok::<(), kernel::error::Error>(())
> +//! ```
> +//!
> +//! ## Using a mutable stack-based timer
> +//!
> +//! ```
> +//! # use kernel::{
> +//! # alloc::flags,
> +//! # impl_has_hr_timer,
> +//! # prelude::*,
> +//! # sync::{
> +//! # atomic::{ordering, Atomic},
> +//! # completion::Completion,
> +//! # Arc,
> +//! # },
> +//! # time::{
> +//! # hrtimer::{
> +//! # ScopedHrTimerPointer, HrTimer, HrTimerCallback, HrTimerPointer, HrTimerRestart,
> +//! # HasHrTimer, RelativeMode, HrTimerCallbackContext
> +//! # },
> +//! # Delta, Monotonic,
> +//! # },
> +//! # };
> +//! # use pin_init::stack_try_pin_init;
> +//!
Ditto.
> +//! #[pin_data]
> +//! struct Shared {
> +//! #[pin]
> +//! flag: Atomic<u64>,
> +//! #[pin]
> +//! cond: Completion,
> +//! }
> +//!
> +//! impl Shared {
> +//! fn new() -> impl PinInit<Self> {
> +//! pin_init!(Self {
> +//! flag <- Atomic::new(0),
> +//! cond <- Completion::new(),
> +//! })
> +//! }
> +//! }
> +//!
> +//! #[pin_data]
> +//! struct IntrusiveHrTimer {
> +//! #[pin]
> +//! timer: HrTimer<Self>,
> +//! shared: Arc<Shared>,
> +//! }
> +//!
> +//! impl IntrusiveHrTimer {
> +//! fn new() -> impl PinInit<Self, kernel::error::Error> {
> +//! try_pin_init!(Self {
> +//! timer <- HrTimer::new(),
> +//! shared: Arc::pin_init(Shared::new(), flags::GFP_KERNEL)?,
> +//! })
> +//! }
> +//! }
> +//!
> +//! impl HrTimerCallback for IntrusiveHrTimer {
> +//! type Pointer<'a> = Pin<&'a mut Self>;
> +//!
> +//! fn run(this: Pin<&mut Self>, _ctx: HrTimerCallbackContext<'_, Self>) -> HrTimerRestart {
> +//! pr_info!("Timer called\n");
> +//!
> +//! let flag = this.shared.flag.fetch_add(1, ordering::Full);
> +//! this.shared.cond.complete_all();
> +//!
> +//! if flag == 4 {
> +//! HrTimerRestart::NoRestart
> +//! } else {
> +//! HrTimerRestart::Restart
> +//! }
> +//! }
> +//! }
> +//!
> +//! impl_has_hr_timer! {
> +//! impl HasHrTimer<Self> for IntrusiveHrTimer {
> +//! mode: RelativeMode<Monotonic>, field: self.timer
> +//! }
> +//! }
> +//!
> +//! stack_try_pin_init!( let has_timer =? IntrusiveHrTimer::new() );
> +//! let shared = has_timer.shared.clone();
> +//!
> +//! has_timer.as_mut().start_scoped(Delta::from_micros(200), || {
> +//! while shared.flag.load(ordering::Relaxed) != 5 {
> +//! shared.cond.wait_for_completion();
> +//! }
> +//! });
> +//!
> +//! pr_info!("Counted to 5\n");
> +//! # Ok::<(), kernel::error::Error>(())
> +//! ```
> +//!
> +//! [`Arc`]: kernel::sync::Arc
>
> use super::{ClockSource, Delta, Instant};
> use crate::{prelude::*, types::Opaque};
>
> ---
> base-commit: 8f0b4cce4481fb22653697cced8d0d04027cb1e8
> change-id: 20251215-hrtimer-examples-v6-19-rc1-2658ce9bb5d0
>
> Best regards,
> --
> Andreas Hindborg <a.hindborg@kernel.org>
>
>
^ permalink raw reply [flat|nested] 5+ messages in thread* Re: [PATCH v2] hrtimer: add usage examples to documentation
2026-02-19 12:31 ` Alice Ryhl
@ 2026-02-19 13:35 ` Andreas Hindborg
2026-02-19 13:39 ` Alice Ryhl
0 siblings, 1 reply; 5+ messages in thread
From: Andreas Hindborg @ 2026-02-19 13:35 UTC (permalink / raw)
To: Alice Ryhl
Cc: Boqun Feng, FUJITA Tomonori, Frederic Weisbecker, Lyude Paul,
Thomas Gleixner, Anna-Maria Behnsen, John Stultz, Stephen Boyd,
Miguel Ojeda, Gary Guo, Björn Roy Baron, Benno Lossin,
Trevor Gross, Danilo Krummrich, rust-for-linux, linux-kernel,
Daniel Almeida
"Alice Ryhl" <aliceryhl@google.com> writes:
> On Thu, Feb 19, 2026 at 12:57:45PM +0100, Andreas Hindborg wrote:
>> Add documentation examples showing various ways to use hrtimers:
>>
>> - Box-allocated timers with shared state in Arc.
>> - Arc-allocated timers.
>> - Stack-based timers for scoped usage.
>> - Mutable stack-based timers with shared state.
>>
>> Tested-by: Daniel Almeida <daniel.almeida@collabora.com>
>> Reviewed-by: Daniel Almeida <daniel.almeida@collabora.com>
>> Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
>
> Reviewed-by: Alice Ryhl <aliceryhl@google.com>
>
>> ---
>> Changes in v2:
>> - Sprinkle blank lines for readability
>> - Change heading for Arc example
>> - Fix error handling.
>> - Link to v1: https://lore.kernel.org/r/20251217-hrtimer-examples-v6-19-rc1-v1-1-4ad0e7e4c4e0@kernel.org
>> ---
>> rust/kernel/time/hrtimer.rs | 336 ++++++++++++++++++++++++++++++++++++++++++++
>> 1 file changed, 336 insertions(+)
>>
>> diff --git a/rust/kernel/time/hrtimer.rs b/rust/kernel/time/hrtimer.rs
>> index 856d2d929a008..2d7f1131a8131 100644
>> --- a/rust/kernel/time/hrtimer.rs
>> +++ b/rust/kernel/time/hrtimer.rs
>> @@ -66,6 +66,342 @@
>> //!
>> //! A `restart` operation on a timer in the **stopped** state is equivalent to a
>> //! `start` operation.
>> +//!
>> +//! When a type implements both `HrTimerPointer` and `Clone`, it is possible to
>> +//! issue the `start` operation while the timer is in the **started** state. In
>> +//! this case the `start` operation is equivalent to the `restart` operation.
>> +//!
>> +//! # Examples
>> +//!
>> +//! ## Using an intrusive timer living in a [`Box`]
>> +//!
>> +//! ```
>> +//! # use kernel::{
>> +//! # alloc::flags,
>> +//! # impl_has_hr_timer,
>> +//! # prelude::*,
>> +//! # sync::{
>> +//! # atomic::{ordering, Atomic},
>> +//! # completion::Completion,
>> +//! # Arc,
>> +//! # },
>> +//! # time::{
>> +//! # hrtimer::{
>> +//! # RelativeMode, HrTimer, HrTimerCallback, HrTimerPointer,
>> +//! # HrTimerRestart, HrTimerCallbackContext
>> +//! # },
>> +//! # Delta, Monotonic,
>> +//! # },
>> +//! # };
>> +//!
>
> Either do not hide the imports, or remove this empty newline.
This got me a few times already.
I'm undecided if it is better to hide the imports or not. What do people
think?
Best regards,
Andreas Hindborg
^ permalink raw reply [flat|nested] 5+ messages in thread* Re: [PATCH v2] hrtimer: add usage examples to documentation
2026-02-19 13:35 ` Andreas Hindborg
@ 2026-02-19 13:39 ` Alice Ryhl
0 siblings, 0 replies; 5+ messages in thread
From: Alice Ryhl @ 2026-02-19 13:39 UTC (permalink / raw)
To: Andreas Hindborg
Cc: Boqun Feng, FUJITA Tomonori, Frederic Weisbecker, Lyude Paul,
Thomas Gleixner, Anna-Maria Behnsen, John Stultz, Stephen Boyd,
Miguel Ojeda, Gary Guo, Björn Roy Baron, Benno Lossin,
Trevor Gross, Danilo Krummrich, rust-for-linux, linux-kernel,
Daniel Almeida
On Thu, Feb 19, 2026 at 2:35 PM Andreas Hindborg <a.hindborg@kernel.org> wrote:
>
> "Alice Ryhl" <aliceryhl@google.com> writes:
>
> > On Thu, Feb 19, 2026 at 12:57:45PM +0100, Andreas Hindborg wrote:
> >> Add documentation examples showing various ways to use hrtimers:
> >>
> >> - Box-allocated timers with shared state in Arc.
> >> - Arc-allocated timers.
> >> - Stack-based timers for scoped usage.
> >> - Mutable stack-based timers with shared state.
> >>
> >> Tested-by: Daniel Almeida <daniel.almeida@collabora.com>
> >> Reviewed-by: Daniel Almeida <daniel.almeida@collabora.com>
> >> Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
> >
> > Reviewed-by: Alice Ryhl <aliceryhl@google.com>
> >
> >> ---
> >> Changes in v2:
> >> - Sprinkle blank lines for readability
> >> - Change heading for Arc example
> >> - Fix error handling.
> >> - Link to v1: https://lore.kernel.org/r/20251217-hrtimer-examples-v6-19-rc1-v1-1-4ad0e7e4c4e0@kernel.org
> >> ---
> >> rust/kernel/time/hrtimer.rs | 336 ++++++++++++++++++++++++++++++++++++++++++++
> >> 1 file changed, 336 insertions(+)
> >>
> >> diff --git a/rust/kernel/time/hrtimer.rs b/rust/kernel/time/hrtimer.rs
> >> index 856d2d929a008..2d7f1131a8131 100644
> >> --- a/rust/kernel/time/hrtimer.rs
> >> +++ b/rust/kernel/time/hrtimer.rs
> >> @@ -66,6 +66,342 @@
> >> //!
> >> //! A `restart` operation on a timer in the **stopped** state is equivalent to a
> >> //! `start` operation.
> >> +//!
> >> +//! When a type implements both `HrTimerPointer` and `Clone`, it is possible to
> >> +//! issue the `start` operation while the timer is in the **started** state. In
> >> +//! this case the `start` operation is equivalent to the `restart` operation.
> >> +//!
> >> +//! # Examples
> >> +//!
> >> +//! ## Using an intrusive timer living in a [`Box`]
> >> +//!
> >> +//! ```
> >> +//! # use kernel::{
> >> +//! # alloc::flags,
> >> +//! # impl_has_hr_timer,
> >> +//! # prelude::*,
> >> +//! # sync::{
> >> +//! # atomic::{ordering, Atomic},
> >> +//! # completion::Completion,
> >> +//! # Arc,
> >> +//! # },
> >> +//! # time::{
> >> +//! # hrtimer::{
> >> +//! # RelativeMode, HrTimer, HrTimerCallback, HrTimerPointer,
> >> +//! # HrTimerRestart, HrTimerCallbackContext
> >> +//! # },
> >> +//! # Delta, Monotonic,
> >> +//! # },
> >> +//! # };
> >> +//!
> >
> > Either do not hide the imports, or remove this empty newline.
>
> This got me a few times already.
>
> I'm undecided if it is better to hide the imports or not. What do people
> think?
I think including the imports is useful to the reader.
Alice
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH v2] hrtimer: add usage examples to documentation
2026-02-19 11:57 [PATCH v2] hrtimer: add usage examples to documentation Andreas Hindborg
2026-02-19 12:31 ` Alice Ryhl
@ 2026-03-23 11:07 ` Andreas Hindborg
1 sibling, 0 replies; 5+ messages in thread
From: Andreas Hindborg @ 2026-03-23 11:07 UTC (permalink / raw)
To: FUJITA Tomonori, Frederic Weisbecker, Lyude Paul,
Anna-Maria Behnsen, John Stultz, Stephen Boyd, Miguel Ojeda,
Gary Guo, Björn Roy Baron, Benno Lossin, Alice Ryhl,
Trevor Gross, Danilo Krummrich, Boqun Feng, Thomas Gleixner,
Andreas Hindborg
Cc: rust-for-linux, linux-kernel, Daniel Almeida
On Thu, 19 Feb 2026 12:57:45 +0100, Andreas Hindborg wrote:
> Add documentation examples showing various ways to use hrtimers:
>
> - Box-allocated timers with shared state in Arc.
> - Arc-allocated timers.
> - Stack-based timers for scoped usage.
> - Mutable stack-based timers with shared state.
>
> [...]
Applied, thanks!
[1/1] hrtimer: add usage examples to documentation
commit: ddb1444d3335129ae87d9796ab1debf41c0ee51b
Best regards,
--
Andreas Hindborg <a.hindborg@kernel.org>
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2026-03-23 11:09 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-02-19 11:57 [PATCH v2] hrtimer: add usage examples to documentation Andreas Hindborg
2026-02-19 12:31 ` Alice Ryhl
2026-02-19 13:35 ` Andreas Hindborg
2026-02-19 13:39 ` Alice Ryhl
2026-03-23 11:07 ` Andreas Hindborg
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox