All of lore.kernel.org
 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: 18+ 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 13:14           ` Danilo Krummrich
2026-11-17 14:16   ` Alice Ryhl
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 14:16   ` Alice Ryhl
2026-11-17  0:14 ` [PATCH v3 3/5] rust: sync: convert CondVar and PollCondVar to use WaitQueue Danilo Krummrich
2026-11-17 14:16   ` Alice Ryhl
2026-11-17  0:14 ` [PATCH v3 4/5] rust: sync: condvar: use task::schedule_timeout() Danilo Krummrich
2026-11-17 14:16   ` Alice Ryhl
2026-11-17 22:06     ` FUJITA Tomonori
2026-11-17  0:14 ` [PATCH v3 5/5] rust: sync: condvar: add non-exclusive freezable waiting Danilo Krummrich
2026-11-17 14:16   ` Alice Ryhl

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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.