Rust for Linux List
 help / color / mirror / Atom feed
From: "Gary Guo" <gary@garyguo.net>
To: "Danilo Krummrich" <dakr@kernel.org>, <boqun@kernel.org>,
	<gary@garyguo.net>, <aliceryhl@google.com>, <lyude@redhat.com>,
	<daniel.almeida@collabora.com>, <work@onurozkan.dev>,
	<ojeda@kernel.org>, <bjorn3_gh@protonmail.com>,
	<lossin@kernel.org>, <a.hindborg@kernel.org>, <tmgross@umich.edu>,
	<tamird@kernel.org>, <acourbot@nvidia.com>,
	<viro@zeniv.linux.org.uk>, <brauner@kernel.org>, <jack@suse.cz>
Cc: <linux-kernel@vger.kernel.org>, <rust-for-linux@vger.kernel.org>,
	<linux-fsdevel@vger.kernel.org>
Subject: Re: [PATCH v3 2/5] rust: sync: add WaitQueue infrastructure
Date: Tue, 17 Nov 2026 11:59:46 +0000	[thread overview]
Message-ID: <DMXGWCITETPM.1OCWS0ISXH5RP@garyguo.net> (raw)
In-Reply-To: <20261117001507.1611984-3-dakr@kernel.org>

On Tue Nov 17, 2026 at 12:14 AM GMT, Danilo Krummrich wrote:
> Implement a wait queue wrapping the kernel's struct wait_queue_head,
> with wait_event()-style methods that take a condition closure directly.
>
> The API mirrors the C wait_event() family:
>
>   - wait_event()
>   - wait_event_interruptible()
>   - wait_event_timeout()
>   - wait_event_interruptible_timeout()
>   - wake_up() / wake_up_all() / wake_up_sync()
>
> The interruptible variant returns Result<(), Interrupted>, the timeout
> variant Result<(), TimedOut>, and the combined variant Result<(),
> WaitError>. These errors map to ERESTARTSYS (signal) or ETIMEDOUT
> (timeout).
>
> Signed-off-by: Danilo Krummrich <dakr@kernel.org>
> ---
>  rust/kernel/Kconfig.test |  10 +
>  rust/kernel/sync.rs      |   8 +
>  rust/kernel/sync/wait.rs | 549 +++++++++++++++++++++++++++++++++++++++
>  3 files changed, 567 insertions(+)
>  create mode 100644 rust/kernel/sync/wait.rs
>
> diff --git a/rust/kernel/Kconfig.test b/rust/kernel/Kconfig.test
> index 3bf4194f28c7..7a1a464b6b29 100644
> --- a/rust/kernel/Kconfig.test
> +++ b/rust/kernel/Kconfig.test
> @@ -104,4 +104,14 @@ config RUST_TIME_KUNIT_TEST
>  
>  	  If unsure, say N.
>  
> +config RUST_WAITQUEUE_KUNIT_TEST
> +	bool "KUnit tests for the Rust wait queue API" if !KUNIT_ALL_TESTS
> +	default KUNIT_ALL_TESTS
> +	help
> +	  This option enables KUnit tests for the Rust wait queue API.
> +	  These are only for development and testing, not for regular
> +	  kernel use cases.
> +
> +	  If unsure, say N.
> +
>  endif
> diff --git a/rust/kernel/sync.rs b/rust/kernel/sync.rs
> index ee372c048a8a..5f7ffd828259 100644
> --- a/rust/kernel/sync.rs
> +++ b/rust/kernel/sync.rs
> @@ -19,6 +19,7 @@
>  mod refcount;
>  mod set_once;
>  pub mod srcu;
> +mod wait;
>  
>  pub use arc::{Arc, ArcBorrow, UniqueArc};
>  pub use completion::Completion;
> @@ -41,3 +42,10 @@
>  pub use refcount::Refcount;
>  pub use set_once::SetOnce;
>  pub use srcu::Srcu;
> +pub use wait::{
> +    new_waitqueue,
> +    Interrupted,
> +    TimedOut,
> +    WaitError,
> +    WaitQueue, //
> +};
> diff --git a/rust/kernel/sync/wait.rs b/rust/kernel/sync/wait.rs
> new file mode 100644
> index 000000000000..abbd5466ff44
> --- /dev/null
> +++ b/rust/kernel/sync/wait.rs
> @@ -0,0 +1,549 @@
> +// SPDX-License-Identifier: GPL-2.0
> +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
> +
> +//! Wait queue.
> +//!
> +//! C header: [`include/linux/wait.h`](srctree/include/linux/wait.h)
> +
> +use super::LockClassKey;
> +use crate::{
> +    prelude::*,
> +    str::CStr,
> +    task,
> +    time::{
> +        Delta,
> +        Jiffy, //
> +    },
> +    types::Opaque, //
> +};
> +
> +use core::{
> +    pin::Pin,
> +    ptr, //
> +};
> +
> +/// Creates a [`WaitQueue`] initialiser with the given name and a newly-created lock class.
> +#[macro_export]
> +macro_rules! new_waitqueue {
> +    ($($name:literal)?) => {
> +        $crate::sync::WaitQueue::new(
> +            $crate::optional_name!($($name)?),
> +            $crate::static_lock_class!(),
> +        )
> +    };
> +}
> +pub use new_waitqueue;
> +
> +/// Exposes the kernel's [`struct wait_queue_head`] as a Rust wait queue.

The first paragraph is rendered as rustdoc short item description so please
have something more descriptive and leave the C equivalence to other pragraphs.

Best,
Gary

> +///
> +/// A `WaitQueue` allows a thread to sleep until a caller-supplied condition becomes true,
> +/// re-checking the condition on each wake-up. This matches the C `wait_event()` family of macros.
> +///
> +/// For waiting with a lock guard (the condition variable pattern), use [`CondVar`](super::CondVar)
> +/// instead.
> +///
> +/// Instances of `WaitQueue` need a lock class and to be pinned. The recommended way to create such
> +/// instances is with the [`pin_init!`] and [`new_waitqueue!`] macros.
> +///
> +/// # Examples
> +///
> +/// ```
> +/// use kernel::sync::{
> +///     atomic::{
> +///         Atomic,
> +///         Relaxed,
> +///     },
> +///     new_waitqueue,
> +///     WaitQueue,
> +/// };
> +///
> +/// #[pin_data]
> +/// pub struct Example {
> +///     value: Atomic<i32>,
> +///     #[pin]
> +///     queue: WaitQueue,
> +/// }
> +///
> +/// fn wait_for_value(e: &Example, v: i32) {
> +///     e.queue.wait_event(|| e.value.load(Relaxed) == v);
> +/// }
> +///
> +/// fn set_value(e: &Example, v: i32) {
> +///     e.value.store(v, Relaxed);
> +///     e.queue.wake_up();
> +/// }
> +/// ```
> +///
> +/// [`struct wait_queue_head`]: srctree/include/linux/wait.h
> +#[pin_data]
> +pub struct WaitQueue {
> +    #[pin]
> +    wait_queue_head: Opaque<bindings::wait_queue_head>,
> +}


  reply	other threads:[~2026-11-17 11:59 UTC|newest]

Thread overview: 11+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-17  0:14 [PATCH v3 0/5] rust: sync: add WaitQueue infrastructure Danilo Krummrich
2026-11-17  0:14 ` [PATCH v3 1/5] rust: task: add safe schedule_timeout() wrapper Danilo Krummrich
2026-11-17  0:45   ` FUJITA Tomonori
2026-11-17 11:40     ` Gary Guo
2026-11-17 11:56       ` Danilo Krummrich
2026-11-17 12:02         ` Gary Guo
2026-11-17  0:14 ` [PATCH v3 2/5] rust: sync: add WaitQueue infrastructure Danilo Krummrich
2026-11-17 11:59   ` Gary Guo [this message]
2026-11-17  0:14 ` [PATCH v3 3/5] rust: sync: convert CondVar and PollCondVar to use WaitQueue Danilo Krummrich
2026-11-17  0:14 ` [PATCH v3 4/5] rust: sync: condvar: use task::schedule_timeout() Danilo Krummrich
2026-11-17  0:14 ` [PATCH v3 5/5] rust: sync: condvar: add non-exclusive freezable waiting Danilo Krummrich

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=DMXGWCITETPM.1OCWS0ISXH5RP@garyguo.net \
    --to=gary@garyguo.net \
    --cc=a.hindborg@kernel.org \
    --cc=acourbot@nvidia.com \
    --cc=aliceryhl@google.com \
    --cc=bjorn3_gh@protonmail.com \
    --cc=boqun@kernel.org \
    --cc=brauner@kernel.org \
    --cc=dakr@kernel.org \
    --cc=daniel.almeida@collabora.com \
    --cc=jack@suse.cz \
    --cc=linux-fsdevel@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=lossin@kernel.org \
    --cc=lyude@redhat.com \
    --cc=ojeda@kernel.org \
    --cc=rust-for-linux@vger.kernel.org \
    --cc=tamird@kernel.org \
    --cc=tmgross@umich.edu \
    --cc=viro@zeniv.linux.org.uk \
    --cc=work@onurozkan.dev \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox