Re: [PATCH v4 3/3] rust: workqueue: add creation of workqueues

["Gary Guo" <gary@garyguo.net>]

On Thu Mar 12, 2026 at 9:23 AM GMT, Alice Ryhl wrote:
> Creating workqueues is needed by various GPU drivers. Not only does it
> give you better control over execution, it also allows devices to ensure
> that all tasks have exited before the device is unbound (or similar) by
> running the workqueue destructor.
>
> Signed-off-by: Alice Ryhl <aliceryhl@google.com>
> ---
>  rust/helpers/workqueue.c         |   7 +
>  rust/kernel/workqueue/builder.rs | 380 +++++++++++++++++++++++++++++++++++++++
>  rust/kernel/workqueue/mod.rs     |  44 ++++-
>  3 files changed, 428 insertions(+), 3 deletions(-)
>
> diff --git a/rust/helpers/workqueue.c b/rust/helpers/workqueue.c
> index ce1c3a5b2150..e4b9d1b3d6bf 100644
> --- a/rust/helpers/workqueue.c
> +++ b/rust/helpers/workqueue.c
> @@ -14,3 +14,10 @@ __rust_helper void rust_helper_init_work_with_key(struct work_struct *work,
>  	INIT_LIST_HEAD(&work->entry);
>  	work->func = func;
>  }
> +
> +__rust_helper
> +struct workqueue_struct *rust_helper_alloc_workqueue(const char *fmt, unsigned int flags,
> +						     int max_active, const void *data)
> +{
> +	return alloc_workqueue(fmt, flags, max_active, data);
> +}
> diff --git a/rust/kernel/workqueue/builder.rs b/rust/kernel/workqueue/builder.rs
> new file mode 100644
> index 000000000000..d4d77b96f9c4
> --- /dev/null
> +++ b/rust/kernel/workqueue/builder.rs
> @@ -0,0 +1,380 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> +//! Workqueue builders.
> +
> +use kernel::{
> +    alloc::AllocError,
> +    prelude::*,
> +    workqueue::{
> +        OwnedQueue, //
> +        Queue,
> +    }, //
> +};
> +
> +use core::{
> +    marker::PhantomData, //
> +    ptr::{self, NonNull},

This is formatted incorrectly.

> +};
> +
> +/// Workqueue builder.
> +///
> +/// A valid combination of workqueue flags contains one of the base flags (`WQ_UNBOUND`, `WQ_BH`,
> +/// or `WQ_PERCPU`) and a combination of modifier flags that are compatible with the selected base
> +/// flag.
> +///
> +/// For details, please refer to `Documentation/core-api/workqueue.rst`.
> +pub struct Builder<T> {

I would name the generic parameter `Kind` rather than `T`. `T` is too generic to
indicate it's for specific kind/type of workqueue.

> +    flags: bindings::wq_flags,
> +    max_active: i32,
> +    _type: PhantomData<T>,

Hmm, it is somewhat awkward to me that we are having a `PhantomData<T>` here,
as `PhantomData` is documented to "behave as it it owns a `T`", but all the
possible `T`s that we use here are uninhabited.

> +}
> +
> +pub enum TypeUnbound {}
> +pub enum TypePercpu {}
> +pub enum TypePowerEfficient {}
> +pub enum TypeBH {}
> +pub enum TypeOrdered {}
> +
> +/// Entry-points to the builder API.
> +impl Queue {
> +    /// Build a workqueue whose work may execute on any cpu.
> +    ///
> +    /// # Examples
> +    ///
> +    /// ```
> +    /// use kernel::workqueue::Queue;
> +    ///
> +    /// let wq = Queue::new_unbound().build(c"my-wq")?;
> +    /// wq.try_spawn(GFP_KERNEL, || pr_info!("Hello from unbound wq"))?;
> +    /// # Ok::<(), Error>(())
> +    /// ```
> +    #[inline]
> +    #[doc(alias = "WQ_UNBOUND")]
> +    pub fn new_unbound() -> Builder<TypeUnbound> {
> +        Builder {
> +            flags: bindings::wq_flags_WQ_UNBOUND,
> +            max_active: 0,
> +            _type: PhantomData,
> +        }
> +    }
> +
> +    /// Build a workqueue whose work is bound to a specific cpu.
> +    ///
> +    /// # Examples
> +    ///
> +    /// ```
> +    /// use kernel::workqueue::Queue;
> +    ///
> +    /// let wq = Queue::new_percpu().build(c"my-wq")?;
> +    /// wq.try_spawn(GFP_KERNEL, || pr_info!("Hello from percpu wq"))?;
> +    /// # Ok::<(), Error>(())
> +    /// ```
> +    #[inline]
> +    #[doc(alias = "WQ_PERCPU")]
> +    pub fn new_percpu() -> Builder<TypePercpu> {
> +        Builder {
> +            flags: bindings::wq_flags_WQ_PERCPU,
> +            max_active: 0,
> +            _type: PhantomData,
> +        }
> +    }
> +
> +    /// Build a power-efficient workqueue.
> +    ///
> +    /// # Examples
> +    ///
> +    /// ```
> +    /// use kernel::workqueue::Queue;
> +    ///
> +    /// let wq = Queue::new_power_efficient().build(c"my-wq")?;
> +    /// wq.try_spawn(GFP_KERNEL, || pr_info!("Hello from power-efficient wq"))?;
> +    /// # Ok::<(), Error>(())
> +    /// ```
> +    #[inline]
> +    #[doc(alias = "WQ_POWER_EFFICIENT")]
> +    pub fn new_power_efficient() -> Builder<TypePowerEfficient> {
> +        Builder {
> +            flags: bindings::wq_flags_WQ_POWER_EFFICIENT,
> +            max_active: 0,
> +            _type: PhantomData,
> +        }
> +    }
> +
> +    /// Build a single-threaded workqueue that executes jobs in order.
> +    ///
> +    /// # Examples
> +    ///
> +    /// ```
> +    /// use kernel::workqueue::Queue;
> +    ///
> +    /// let wq = Queue::new_ordered().build(c"my-wq")?;
> +    /// wq.try_spawn(GFP_KERNEL, || pr_info!("Hello from ordered wq"))?;
> +    /// # Ok::<(), Error>(())
> +    /// ```
> +    #[inline]
> +    #[doc(alias = "alloc_ordered_workqueue")]
> +    #[doc(alias = "__WQ_ORDERED")]
> +    pub fn new_ordered() -> Builder<TypeOrdered> {
> +        Builder {
> +            flags: bindings::wq_flags_WQ_UNBOUND | bindings::wq_flags___WQ_ORDERED,
> +            max_active: 0,

This should be 1 instead of 0.

> +            _type: PhantomData,
> +        }
> +    }
> +
> +    /// Build a workqueue that executes in bottom-half (softirq) context.
> +    ///
> +    /// # Examples
> +    ///
> +    /// ```
> +    /// use kernel::workqueue::Queue;
> +    ///
> +    /// let wq = Queue::new_bh().build(c"my-wq")?;
> +    /// wq.try_spawn(GFP_KERNEL, || pr_info!("Hello from BH wq"))?;
> +    /// # Ok::<(), Error>(())
> +    /// ```
> +    #[inline]
> +    #[doc(alias = "WQ_BH")]
> +    pub fn new_bh() -> Builder<TypeBH> {
> +        Builder {
> +            flags: bindings::wq_flags_WQ_BH,
> +            max_active: 0,
> +            _type: PhantomData,
> +        }
> +    }
> +}
> +
>
> [snip]
>
> diff --git a/rust/kernel/workqueue/mod.rs b/rust/kernel/workqueue/mod.rs
> index 1acd113c04ee..6049c0e8e4b6 100644
> --- a/rust/kernel/workqueue/mod.rs
> +++ b/rust/kernel/workqueue/mod.rs
> @@ -186,7 +186,10 @@
>  //! C header: [`include/linux/workqueue.h`](srctree/include/linux/workqueue.h)
>  
>  use crate::{
> -    alloc::{AllocError, Flags},
> +    alloc::{
> +        self,
> +        AllocError, //
> +    },
>      container_of,
>      prelude::*,
>      sync::Arc,
> @@ -194,7 +197,14 @@
>      time::Jiffies,
>      types::Opaque,
>  };
> -use core::marker::PhantomData;
> +use core::{
> +    marker::PhantomData,
> +    ops::Deref,
> +    ptr::NonNull, //
> +};
> +
> +mod builder;
> +pub use self::builder::Builder;
>  
>  /// Creates a [`Work`] initialiser with the given name and a newly-created lock class.
>  #[macro_export]
> @@ -340,7 +350,7 @@ pub fn enqueue_delayed<W, const ID: u64>(
>      /// This method can fail because it allocates memory to store the work item.
>      pub fn try_spawn<T: 'static + Send + FnOnce()>(
>          &self,
> -        flags: Flags,
> +        flags: alloc::Flags,
>          func: T,
>      ) -> Result<(), AllocError> {
>          let init = pin_init!(ClosureWork {
> @@ -353,6 +363,34 @@ pub fn try_spawn<T: 'static + Send + FnOnce()>(
>      }
>  }
>  
> +/// An owned kernel work queue.
> +///
> +/// Dropping a workqueue blocks on all pending work.
> +///
> +/// # Invariants
> +///
> +/// `queue` points at a valid workqueue that is owned by this `OwnedQueue`.
> +pub struct OwnedQueue {
> +    queue: NonNull<Queue>,
> +}

This looks like something that can become `Owned<Queue>` when Andreas' series
land?

> +
> +impl Deref for OwnedQueue {
> +    type Target = Queue;

#[inline]

Best,
Gary

> +    fn deref(&self) -> &Queue {
> +        // SAFETY: By the type invariants, this pointer references a valid queue.
> +        unsafe { &*self.queue.as_ptr() }
> +    }
> +}
> +
> +impl Drop for OwnedQueue {
> +    fn drop(&mut self) {
> +        // SAFETY: This `OwnedQueue` owns a valid workqueue, so we can destroy it. There is no
> +        // delayed work scheduled on this queue that may attempt to use it after this call, as
> +        // scheduling delayed work requires a 'static reference.
> +        unsafe { bindings::destroy_workqueue(self.queue.as_ptr().cast()) }
> +    }
> +}
> +
>  /// A helper type used in [`try_spawn`].
>  ///
>  /// [`try_spawn`]: Queue::try_spawn