Re: [PATCH v2] hrtimer: add usage examples to documentation

[Andreas Hindborg]

"Alice Ryhl" <aliceryhl@xxxxxxxxxx> 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@xxxxxxxxxxxxx>
>> Reviewed-by: Daniel Almeida <daniel.almeida@xxxxxxxxxxxxx>
>> Signed-off-by: Andreas Hindborg <a.hindborg@xxxxxxxxxx>
>
> Reviewed-by: Alice Ryhl <aliceryhl@xxxxxxxxxx>
>
>> ---
>> 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@xxxxxxxxxx
>> ---
>>  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