Skip to contentSkip to conversation

workqueue: OwnedQueue, ScopedQueue and ScopedWork

PATCH In review Danilo Krummrich 5 participants 21 messages Aug 7 – Sep 12

Subsystems (7)
lore
Share & tools
lore

Danilo Krummrich

author maintainer
#0 lore raw

v2 cover workqueue: OwnedQueue, ScopedQueue and ScopedWork

This series extends the Rust workqueue bindings with the ability to create custom workqueues, enqueue non-'static work items on scoped queues, and introduces ScopedWork, a work item type that cancels synchronously on drop, allowing drivers to use workqueues with lifetime-bound data.

This picks up and extends prior work from Alice [1] and Onur [2]; changes I subsequently applied, if any, are documented in the corresponding patch.

I also added a patch to replace the deprecated system_wq with system_{percpu,dfl}_wq, which I originally sent with the WaitQueue series [3], as it makes a bit more sense in this context.

[1] https://lore.kernel.org/all/[email protected]
[2] https://lore.kernel.org/all/[email protected]
[3] https://lore.kernel.org/all/[email protected]

Changes in v2:
- Merge scoped_work.rs and scoped_queue.rs into scoped.rs
- Introduce ScopedWorkRef<T> and wrap it in Opaque inside ScopedWork to avoid &mut aliasing in drop
- Pass &ScopedWorkRef<Self> to ScopedWorkItem::run to enable self-re-enqueue
- Add Deref<Target = Queue> for ScopedQueue; remove duplicate enqueue_scoped()
- Add Send + Sync for OwnedQueue
- Fix stale workqueue::system() references in docs
- Drop Work::cancel_work_sync()
- Make sysfs() available on ordered workqueues
- Add #[inline] annotations throughout

Alice Ryhl (3):
rust: workqueue: restrict delayed work to global wqs
rust: workqueue: create workqueue subdirectory
rust: workqueue: add creation of workqueues

Danilo Krummrich (2):
rust: workqueue: replace deprecated system_wq with
system_{percpu,dfl}_wq
rust: workqueue: add ScopedWork for non-'static work items

Onur Özkan (1):
rust: workqueue: add ScopedQueue for lifetime bound items

 Documentation/rust/testing.rst                |   2 +-
 .../translations/zh_CN/rust/testing.rst       |   2 +-
 MAINTAINERS                                   |   1 +
 drivers/android/binder/process.rs             |   4 +-
 rust/helpers/workqueue.c                      |   7 +
 rust/kernel/sync/completion.rs                |   2 +-
 rust/kernel/workqueue/builder.rs              | 389 ++++++++++++
 .../kernel/{workqueue.rs => workqueue/mod.rs} | 149 ++++-
 rust/kernel/workqueue/scoped.rs               | 568 ++++++++++++++++++
 9 files changed, 1089 insertions(+), 35 deletions(-)
 create mode 100644 rust/kernel/workqueue/builder.rs
 rename rust/kernel/{workqueue.rs => workqueue/mod.rs} (90%)
 create mode 100644 rust/kernel/workqueue/scoped.rs

base-commit: b48373c901951fad1a26bd7c33ad91172b3945b5

Signature · 1 line
2.55.0
author maintainer
#1 lore raw

PATCH v2 1/6 rust: workqueue: replace deprecated system_wq with system_{percpu,dfl}_wq

system_wq is deprecated and triggers a runtime warning:

	[    0.857414] workqueue: work func ...WorkItemPointerKy0_E3runB7_ enqueued on deprecated workqueue. Use system_{percpu|dfl}_wq instead.

Replace system() with system_percpu() and system_dfl(), to match the previous behavior of the deprecated system() and convert doc examples and tests to system_dfl().

---
 Documentation/rust/testing.rst                |  2 +-
 .../translations/zh_CN/rust/testing.rst       |  2 +-
 drivers/android/binder/process.rs             |  4 +-
 rust/kernel/sync/completion.rs                |  2 +-
 rust/kernel/workqueue.rs                      | 42 ++++++++++++-------
 5 files changed, 32 insertions(+), 20 deletions(-)
Documentation/rust/testing.rst +1 -1
index e3943aceceb9..73046523a9a2 100644
@@ -97,7 +97,7 @@ operator are also supported as usual, e.g.:
 
 	/// ```
 	/// # use kernel::{spawn_work_item, workqueue};
-	/// spawn_work_item!(workqueue::system(), || pr_info!("x\n"))?;
+	/// spawn_work_item!(workqueue::system_dfl(), || pr_info!("x\n"))?;
 	/// # Ok::<(), Error>(())
 	/// ```
 
Documentation/translations/zh_CN/rust/testing.rst +1 -1
index ca81f1cef6eb..5fdd553f2b41 100644
@@ -93,7 +93,7 @@ KUnit 测试即文档测试
 
 	/// ```
 	/// # use kernel::{spawn_work_item, workqueue};
-	/// spawn_work_item!(workqueue::system(), || pr_info!("x\n"))?;
+	/// spawn_work_item!(workqueue::system_dfl(), || pr_info!("x\n"))?;
 	/// # Ok::<(), Error>(())
 	/// ```
 
drivers/android/binder/process.rs +2 -2
index 96b8440ceac6..c0266fdaa598 100644
@@ -1632,7 +1632,7 @@ pub(crate) fn release(this: Arc<Process>, _file: &File) {
         if should_schedule {
             // Ignore failures to schedule to the workqueue. Those just mean that we're already
             // scheduled for execution.
-            let _ = workqueue::system().enqueue(this);
+            let _ = workqueue::system_percpu().enqueue(this);
         }
 
         drop(binderfs_file);
@@ -1649,7 +1649,7 @@ pub(crate) fn flush(this: ArcBorrow<'_, Process>) -> Result {
         if should_schedule {
             // Ignore failures to schedule to the workqueue. Those just mean that we're already
             // scheduled for execution.
-            let _ = workqueue::system().enqueue(Arc::from(this));
+            let _ = workqueue::system_percpu().enqueue(Arc::from(this));
         }
         Ok(())
     }
rust/kernel/sync/completion.rs +1 -1
index 35ff049ff078..1771bfc0ade2 100644
@@ -38,7 +38,7 @@
 ///             done <- Completion::new(),
 ///         }), GFP_KERNEL)?;
 ///
-///         let _ = workqueue::system().enqueue(this.clone());
+///         let _ = workqueue::system_dfl().enqueue(this.clone());
 ///
 ///         Ok(this)
 ///     }
rust/kernel/workqueue.rs +27 -15

107 lines not on this page · raw message

Signature · 1 line
2.55.0
author maintainer
#3 lore raw

PATCH v2 2/6 rust: workqueue: restrict delayed work to global wqs

In reply to Danilo Krummrich

From: Alice Ryhl <[email protected]>

When a workqueue is shut down, delayed work that is pending but not scheduled does not get properly cleaned up, so it's not safe to use enqueue_delayed on a workqueue that might be destroyed. To fix this, restricted enqueue_delayed to static queues.

This may be fixed in the future by an approach along the lines of [1].

---
 rust/kernel/workqueue.rs | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)
rust/kernel/workqueue.rs +8 -1
index 7bc07ccd1ebb..399d2ed24135 100644
@@ -302,8 +302,15 @@ pub fn enqueue<W, const ID: u64>(&self, w: W) -> W::EnqueueOutput
     ///
     /// This may fail if the work item is already enqueued in a workqueue.
     ///
+    /// This is only valid for global workqueues (with static lifetimes) because those are the only
+    /// ones that outlive all possible delayed work items.
+    ///
     /// The work item will be submitted using `WORK_CPU_UNBOUND`.
-    pub fn enqueue_delayed<W, const ID: u64>(&self, w: W, delay: Jiffies) -> W::EnqueueOutput
+    pub fn enqueue_delayed<W, const ID: u64>(
+        &'static self,
+        w: W,
+        delay: Jiffies,
+    ) -> W::EnqueueOutput
     where
         W: RawDelayedWorkItem<ID> + Send + 'static,
     {
Signature · 1 line
2.55.0
author maintainer
#5 lore raw

PATCH v2 3/6 rust: workqueue: create workqueue subdirectory

In reply to Danilo Krummrich

From: Alice Ryhl <[email protected]>

The following patch will implement a workqueue builder in a separate file. To prepare for that, create a rust/kernel/workqueue subdirectory and move the existing file.

---
 MAINTAINERS                                    | 1 +
 rust/kernel/{workqueue.rs => workqueue/mod.rs} | 0
 2 files changed, 1 insertion(+)
 rename rust/kernel/{workqueue.rs => workqueue/mod.rs} (100%)
MAINTAINERS +1 -0
index f672858996f0..9cee804d840d 100644
@@ -29155,6 +29155,7 @@ F:	Documentation/core-api/workqueue.rst
 F:	include/linux/workqueue.h
 F:	kernel/workqueue.c
 F:	kernel/workqueue_internal.h
+F:	rust/kernel/workqueue/
 
 WWAN DRIVERS
 M:	Loic Poulain <[email protected]>
rust/kernel/workqueue/mod.rs renamed from rust/kernel/workqueue.rs +0 -0
similarity index 100%
rename from rust/kernel/workqueue.rs
rename to rust/kernel/workqueue/mod.rs
Signature · 1 line
2.55.0
author maintainer
#7 lore raw

PATCH v2 4/6 rust: workqueue: add creation of workqueues

In reply to Danilo Krummrich

From: Alice Ryhl <[email protected]>

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.

[ * Fix import formatting of ptr::{self, NonNull},
* rename T to Kind,
* new_ordered(): set max_active: 1,
* new_power_efficient(): WQ_UNBOUND | WQ_POWER_EFFICIENT, add

    .percpu(),

* new_bh(): WQ_PERCPU | WQ_BH, removed .percpu(),
* move sysfs() to TypeNormal,
* impl Send + Sync for OwnedQueue,
* add missing inline annotations,
* various doc improvements: new_percpu, max_active, cpu_intensive, freezable.

- Danilo ]

---
 rust/helpers/workqueue.c         |   7 +
 rust/kernel/workqueue/builder.rs | 389 +++++++++++++++++++++++++++++++
 rust/kernel/workqueue/mod.rs     |  51 +++-
 3 files changed, 444 insertions(+), 3 deletions(-)
 create mode 100644 rust/kernel/workqueue/builder.rs
rust/helpers/workqueue.c +7 -0
index ce1c3a5b2150..e4b9d1b3d6bf 100644
@@ -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);
+}
rust/kernel/workqueue/builder.rs new file +389 -0

389 lines not on this page · raw message

rust/kernel/workqueue/mod.rs +48 -3

75 lines not on this page · raw message

Signature · 1 line
2.55.0
author maintainer
#11 lore raw

PATCH v2 5/6 rust: workqueue: add ScopedQueue for lifetime bound items

In reply to Danilo Krummrich

From: Onur Özkan <[email protected]>

Add a workqueue wrapper for work items that are not 'static.

Tyr reset work is queued from a handle that owns a Controller<'bound> where the work item holds references tied to the lifetime of the bound device and its mapped IO state. The existing API only accepts 'static work items which cannot express that relationship.

Introduce ScopedQueue for this case. It owns the underlying workqueue and ties enqueued work to the queue lifetime so borrowed state cannot outlive the queue that may still run it.

Construction is unsafe because the queue must not be leaked.

compile_fail doc-tests are ignored for now as KUnit doesn't support that. Enabling those tests as regular code block would raise this error:

    ERROR:root:error[E0597]: `data` does not live long enough
	 --> rust/doctests_kernel_generated.rs:22029:44
	  |
    22027 |         let data = ();
	  |             ---- binding `data` declared here
    22028 |         // SAFETY: Queue is not leaked.
    22029 |         queue = unsafe { new_queue(&data)? };
	  |                                            ^^^^^ borrowed value does not live long enough
    22030 |     }
	  |     - `data` dropped here while still borrowed
    ...
    22034 | }
	  | - borrow might be used here, when `queue` is dropped and runs the `Drop` code for type `ScopedQueue`
	  |
	  = note: values in a scope are dropped in the opposite order they are defined

which is exactly the constraint ScopedQueue is meant to enforce.

[ Move from scoped_queue.rs to scoped.rs, which can be shared with
ScopedWork; add missing inline annotations. - Danilo ]

---
 rust/kernel/workqueue/mod.rs    |   3 +
 rust/kernel/workqueue/scoped.rs | 190 ++++++++++++++++++++++++++++++++
 2 files changed, 193 insertions(+)
 create mode 100644 rust/kernel/workqueue/scoped.rs
rust/kernel/workqueue/mod.rs +3 -0
index 8eb2d037be83..551fa1401b85 100644
@@ -212,6 +212,9 @@
 mod builder;
 pub use self::builder::Builder;
 
+mod scoped;
+pub use self::scoped::ScopedQueue;
+
 /// Creates a [`Work`] initialiser with the given name and a newly-created lock class.
 #[macro_export]
 macro_rules! new_work {
rust/kernel/workqueue/scoped.rs new file +190 -0

190 lines not on this page · raw message

Signature · 1 line
2.55.0
author maintainer
#16 lore raw

PATCH v2 6/6 rust: workqueue: add ScopedWork for non-'static work items

In reply to Danilo Krummrich

Add ScopedWork<T>, a work item wrapper whose destructor calls cancel_work_sync(), allowing T to carry non-'static lifetimes. Ownership of the data is not transferred to the workqueue; instead, the synchronous cancellation on drop guarantees the work function is not running when the data is freed.

ScopedWork uses the existing Work/HasWork/WorkItem infrastructure with NonNull<ScopedWorkRef<T>> as WorkItem::Pointer for the callback path, and implements RawWorkItem for &ScopedWork<T> and &ScopedWorkRef<T> for the enqueue path (requiring T: Sync for cross-thread shared access safety).

Two enqueue paths are provided:
- Queue::enqueue_scoped() (unsafe): the caller must ensure the work item is not forgotten.
- ScopedQueue::enqueue() (safe): when the work item's lifetime satisfies the queue's 'scope bound.

---
 rust/kernel/workqueue/mod.rs    |  46 +++-
 rust/kernel/workqueue/scoped.rs | 442 +++++++++++++++++++++++++++++---
 2 files changed, 444 insertions(+), 44 deletions(-)
rust/kernel/workqueue/mod.rs +34 -12
index 551fa1401b85..be5bfb4cfc30 100644
@@ -213,7 +213,13 @@
 pub use self::builder::Builder;
 
 mod scoped;
-pub use self::scoped::ScopedQueue;
+pub use self::scoped::{
+    new_scoped_work,
+    ScopedQueue,
+    ScopedWork,
+    ScopedWorkItem,
+    ScopedWorkRef, //
+};
 
 /// Creates a [`Work`] initialiser with the given name and a newly-created lock class.
 #[macro_export]
@@ -283,23 +289,39 @@ pub unsafe fn from_raw<'a>(ptr: *const bindings::workqueue_struct) -> &'a Queue
     /// This may fail if the work item is already enqueued in a workqueue.
     ///
     /// The work item will be submitted using `WORK_CPU_UNBOUND`.
+    #[inline]
     pub fn enqueue<W, const ID: u64>(&self, w: W) -> W::EnqueueOutput
     where
         W: RawWorkItem<ID> + Send + 'static,
+    {
+        // SAFETY: `W: 'static` guarantees the work item remains valid indefinitely,
+        // so the `enqueue_scoped` requirement that the work item stays valid until
+        // the work function runs (or is cancelled) is trivially satisfied.
+        unsafe { self.enqueue_scoped(w) }
+    }
+
+    /// Enqueues a work item that may not be `'static`.
+    ///
+    /// Unlike [`Queue::enqueue`], this does not require the work item to be `'static`.
+    ///
+    /// The work item will be submitted using `WORK_CPU_UNBOUND`.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that the work item's destructor runs before any
+    /// lifetime it captures expires (i.e., the work item must not be forgotten).
+    #[inline]
+    pub unsafe fn enqueue_scoped<W, const ID: u64>(&self, w: W) -> W::EnqueueOutput
+    where
+        W: RawWorkItem<ID> + Send,
     {
         let queue_ptr = self.0.get();
 
-        // SAFETY: We only return `false` if the `work_struct` is already in a workqueue. The other
-        // `__enqueue` requirements are not relevant since `W` is `Send` and static.
-        //
-        // The call to `bindings::queue_work_on` will dereference the provided raw pointer, which
-        // is ok because `__enqueue` guarantees that the pointer is valid for the duration of this
-        // closure.
-        //
-        // Furthermore, if the C workqueue code accesses the pointer after this call to
-        // `__enqueue`, then the work item was successfully enqueued, and `bindings::queue_work_on`
-        // will have returned true. In this case, `__enqueue` promises that the raw pointer will
-        // stay valid until we call the function pointer in the `work_struct`, so the access is ok.
+        // SAFETY: We only return `false` if the `work_struct` is already in a workqueue. The
+        // caller guarantees the work item remains valid until the work function runs or the item
+        // is cancelled, satisfying the `__enqueue` requirement that the pointer stays valid until
+        // the function pointer in the `work_struct` is called. `W: Send` satisfies the
+        // cross-thread safety requirement.
         unsafe {
             w.__enqueue(move |work_ptr| {
                 bindings::queue_work_on(
rust/kernel/workqueue/scoped.rs +410 -32

478 lines not on this page · raw message

Signature · 1 line
2.55.0
author maintainer
#17 lore raw

Re: [PATCH v2 6/6] rust: workqueue: add ScopedWork for non-'static work items

rust/kernel/workqueue/scoped.rs fn drop(&mut self) { · line 520

Quoted 9 lines · Danilo Krummrich
rust/kernel/workqueue/scoped.rs +9 -0
+#[pinned_drop]
+impl<T: ScopedWorkItem> PinnedDrop for ScopedWork<T> {
+    #[inline]
+    fn drop(self: Pin<&mut Self>) {
+        let inner = self.inner.get();
+
+        // SAFETY: `inner` points to a valid `ScopedWorkRef`. After `cancel_work_sync()` returns,
+        // the work function is guaranteed to not be running.
+        unsafe { bindings::cancel_work_sync(Work::raw_get(&raw const (*inner).work)) };
	// SAFETY: `inner` is valid and no longer accessed by the work function.
	unsafe { core::ptr::drop_in_place(inner) };
Quoted 2 lines
(quoted diff) +2 -0
+    }
+}
author maintainer
#8 lore raw

Re: [PATCH v2 4/6] rust: workqueue: add creation of workqueues

In reply to Danilo Krummrich
Quoted 2 lines · Danilo Krummrich

* new_power_efficient(): WQ_UNBOUND | WQ_POWER_EFFICIENT, add

    .percpu(),

[...]

rust/kernel/workqueue/builder.rs line 100

Quoted 3 lines
rust/kernel/workqueue/builder.rs new file +3 -0
+    pub fn new_power_efficient() -> Builder<TypePowerEfficient> {
+        Builder {
+            flags: bindings::wq_flags_WQ_UNBOUND | bindings::wq_flags_WQ_POWER_EFFICIENT,

I actually meant to add WQ_PERCPU, which should be the default for WQ_POWER_EFFICIENT, in order to avoid the warning below.

But I somehow managed to fix it the wrong way around and made WQ_UNBOUND the default.

So, this should just be bindings::wq_flags_WQ_PERCPU | bindings::wq_flags_WQ_POWER_EFFICIENT.

- Danilo

[    1.381581] workqueue: my-wq is using neither WQ_PERCPU or WQ_UNBOUND. Setting WQ_PERCPU.
[    1.382274] WARNING: kernel/workqueue.c:5852 at alloc_workqueue_va+0x794/0x800, CPU#0: kunit_try_catch/851
[    1.383088] Modules linked in:
[    1.383359] CPU: 0 UID: 0 PID: 851 Comm: kunit_try_catch Tainted: G        W        N  7.2.0-rc1+ #67 PREEMPT(full)
[    1.384236] Tainted: [W]=WARN, [N]=TEST
[    1.384567] Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS Arch Linux 1.17.0-2-2 04/01/2014
[    1.385364] RIP: 0010:alloc_workqueue_va+0x79b/0x800
[    1.385784] Code: 49 8d 96 b8 00 00 00 b9 01 00 00 00 41 b8 00 08 00 00 e8 08 83 ef ff e9 88 f9 ff ff 48 8d 3d cc 1c e2 01 49 8d b6 b8 00 00 00 <67> 48 0f b9 3a 41 81 cc 00 01 00 00 e9 40 f9 ff ff 48 8d 3d bd 1c
[    1.387337] RSP: 0018:ffffc90000473d58 EFLAGS: 00010246
[    1.387779] RAX: 0000000000000000 RBX: ffff888102041600 RCX: 8313f7e158b49600
[    1.388382] RDX: ffff8881020416d8 RSI: ffff8881020416b8 RDI: ffffffff8312e020
[    1.388985] RBP: 0000000000000000 R08: 00000000ffffffff R09: 00000000ffffffff
[    1.389587] R10: ffff8881020416bd R11: 0000000000000000 R12: 0000000000000080
[    1.390192] R13: ffffffff82ad53fd R14: ffff888102041600 R15: ffffc90000473de0
[    1.390793] FS:  0000000000000000(0000) GS:ffff8881b81cf000(0000) knlGS:0000000000000000
[    1.391478] CS:  0010 DS: 0000 ES: 0000 CR0: 0000000080050033
[    1.391968] CR2: ffff88813ffff000 CR3: 0000000002e22000 CR4: 0000000000750ef0
[    1.392568] PKRU: 55555554
[    1.392804] Call Trace:
[    1.393027]  <TASK>
[    1.393219]  alloc_workqueue_noprof+0x5b/0x80
[    1.393594]  rust_doctest_kernel_workqueue_builder_rs_12+0x3a/0x1f0
[    1.394129]  ? _task_rq_lock+0x55/0x150
[    1.394462]  ? call_rcu+0xec/0x270
[    1.394756]  ? kvm_clock_get_cycles+0x18/0x40
[    1.395136]  ? ktime_get_ts64+0x6d/0x170
[    1.395477]  kunit_try_run_case+0x93/0x190
[    1.395826]  kunit_generic_run_threadfn_adapter+0x22/0x40
[    1.396290]  ? kunit_try_catch_run+0x210/0x210
[    1.396670]  kthread+0xfb/0x120
[    1.396942]  ? kthread_blkcg+0x40/0x40
[    1.397270]  ret_from_fork+0xee/0x260
[    1.397590]  ? kthread_blkcg+0x40/0x40
[    1.397910]  ret_from_fork_asm+0x11/0x20
[    1.398255]  </TASK>
[    1.398453] ---[ end trace 0000000000000000 ]---
#9 lore raw

Re: [PATCH v2 4/6] rust: workqueue: add creation of workqueues

In reply to Danilo Krummrich
Quoted 14 lines · Danilo Krummrich
Quoted 2 lines · Danilo Krummrich

* new_power_efficient(): WQ_UNBOUND | WQ_POWER_EFFICIENT, add .percpu(),

[...]

rust/kernel/workqueue/builder.rs line 100

Quoted 3 lines
rust/kernel/workqueue/builder.rs new file +3 -0
+    pub fn new_power_efficient() -> Builder<TypePowerEfficient> {
+        Builder {
+            flags: bindings::wq_flags_WQ_UNBOUND | bindings::wq_flags_WQ_POWER_EFFICIENT,
Quoted 9 lines

I actually meant to add WQ_PERCPU, which should be the default for WQ_POWER_EFFICIENT, in order to avoid the warning below.

But I somehow managed to fix it the wrong way around and made WQ_UNBOUND the default.

So, this should just be bindings::wq_flags_WQ_PERCPU | bindings::wq_flags_WQ_POWER_EFFICIENT.

It seems that if you make this change, then Builder<TypePowerEfficient>::percpu() doesn’t do anything anymore, IIUC? Perhaps it should be removed then?

reviewer Reviewed-by on v2 5/6
#12 lore raw

Re: [PATCH v2 5/6] rust: workqueue: add ScopedQueue for lifetime bound items

In reply to Danilo Krummrich
Quoted 81 lines · Danilo Krummrich

From: Onur Özkan <[email protected]>

Add a workqueue wrapper for work items that are not 'static.

Tyr reset work is queued from a handle that owns a Controller<'bound> where the work item holds references tied to the lifetime of the bound device and its mapped IO state. The existing API only accepts 'static work items which cannot express that relationship.

Introduce ScopedQueue for this case. It owns the underlying workqueue and ties enqueued work to the queue lifetime so borrowed state cannot outlive the queue that may still run it.

Construction is unsafe because the queue must not be leaked.

compile_fail doc-tests are ignored for now as KUnit doesn't support that. Enabling those tests as regular code block would raise this error:

ERROR:root:error[E0597]: data does not live long enough
--> rust/doctests_kernel_generated.rs:22029:44
|
22027 | let data = ();
| ---- binding data declared here

   22028 |         // SAFETY: Queue is not leaked.
   22029 |         queue = unsafe { new_queue(&data)? };

| ^^^^^ borrowed value does not live long enough
22030 | }
| - data dropped here while still borrowed
...
22034 | }
| - borrow might be used here, when queue is dropped and runs the Drop code for type ScopedQueue |
= note: values in a scope are dropped in the opposite order they are defined

which is exactly the constraint ScopedQueue is meant to enforce.

[ Move from scoped_queue.rs to scoped.rs, which can be shared with
ScopedWork; add missing inline annotations. - Danilo ]

---
rust/kernel/workqueue/mod.rs | 3 +
rust/kernel/workqueue/scoped.rs | 190 ++++++++++++++++++++++++++++++++

2 files changed, 193 insertions(+)

create mode 100644 rust/kernel/workqueue/scoped.rs

rust/kernel/workqueue/mod.rs +3 -0
index 8eb2d037be83..551fa1401b85 100644
@@ -212,6 +212,9 @@
 mod builder;
 pub use self::builder::Builder;
 
+mod scoped;
+pub use self::scoped::ScopedQueue;
+
 /// Creates a [`Work`] initialiser with the given name and a newly-created lock class.
 #[macro_export]
 macro_rules! new_work {
rust/kernel/workqueue/scoped.rs new file +10 -0
new file mode 100644
index 000000000000..18a4b6f6cf18
@@ -0,0 +1,190 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Lifetime-scoped workqueues.
+//!
+//! Provides [`ScopedQueue`] for work items that may borrow data with some
+//! non-`'static` lifetime.
+//!
+//! Unlike [`Queue`] which only accepts `'static` work items, [`ScopedQueue`]
+//! owns its underlying queue and relies on that queue being dropped to drain
+//! pending and running work before borrowed data can go out of scope.

rust/kernel/workqueue/scoped.rs line 20

Quoted 10 lines
rust/kernel/workqueue/scoped.rs new file +10 -0
+//!
+//! TODO: Remove `ignore` once KUnit supports `compile_fail` on doc-tests.
+//! ```compile_fail,ignore
+//! use kernel::prelude::*;
+//! use kernel::workqueue::ScopedQueue;
+//!
+//! /// # Safety
+//! ///
+//! /// Returned queue must not be leaked.
+//! unsafe fn new_queue<'bound>(_: &'bound ()) -> Result<ScopedQueue<'bound>> {

nit: is it me, or “bound” sounds out of place here? Perhaps ’scope instead?

Same comment throughout the whole example.

Quoted 115 lines
rust/kernel/workqueue/scoped.rs new file +115 -0
+//!     // SAFETY: Caller guarantees that the returned queue is not leaked.
+//!     unsafe { ScopedQueue::new(c"scoped_queue") }
+//! }
+//!
+//! fn queue_outlives_borrowed_data() -> Result {
+//!     let queue;
+//!
+//!     {
+//!         let data = ();
+//!         // SAFETY: Queue is not leaked.
+//!         queue = unsafe { new_queue(&data)? };
+//!     }
+//!     // Here the `compile_fail` is fulfilled as `queue` would be dropped
+//!     // after `data`.
+//!     Ok(())
+//! }
+//! ```
+//!
+//! TODO: Remove `ignore` once KUnit supports `compile_fail` on doc-tests.
+//! ```compile_fail,ignore
+//! use kernel::prelude::*;
+//! use kernel::sync::Arc;
+//! use kernel::workqueue::{
+//!     impl_has_work,
+//!     new_work,
+//!     ScopedQueue,
+//!     Work,
+//!     WorkItem,
+//! };
+//!
+//! #[pin_data]
+//! struct BorrowedWork<'bound> {
+//!     data: &'bound (),
+//!     #[pin]
+//!     work: Work<BorrowedWork<'bound>>,
+//! }
+//!
+//! impl_has_work! {
+//!     impl{'bound} HasWork<BorrowedWork<'bound>> for BorrowedWork<'bound> { self.work }
+//! }
+//!
+//! impl<'bound> WorkItem for BorrowedWork<'bound> {
+//!     type Pointer = Arc<Self>;
+//!
+//!     fn run(_this: Arc<Self>) {}
+//! }
+//!
+//! impl<'bound> BorrowedWork<'bound> {
+//!     fn new(data: &'bound ()) -> Result<Arc<Self>> {
+//!         Arc::pin_init(
+//!             pin_init!(Self {
+//!                 data,
+//!                 work <- new_work!("BorrowedWork::work"),
+//!             }),
+//!             GFP_KERNEL,
+//!         )
+//!     }
+//! }
+//!
+//! struct Handle<'bound> {
+//!     work: Arc<BorrowedWork<'bound>>,
+//!     wq: ScopedQueue<'bound>,
+//! }
+//!
+//! impl<'bound> Handle<'bound> {
+//!     /// # Safety
+//!     ///
+//!     /// Returned handle must not be leaked.
+//!     unsafe fn new(data: &'bound ()) -> Result<Self> {
+//!         Ok(Self {
+//!             work: BorrowedWork::new(data)?,
+//!             // SAFETY: Caller guarantees that the returned handle is not leaked.
+//!             wq: unsafe { ScopedQueue::new(c"handle_wq")? },
+//!         })
+//!     }
+//! }
+//!
+//! fn handle_outlives_borrowed_data() -> Result {
+//!     let handle;
+//!
+//!     {
+//!         let data = ();
+//!         // SAFETY: Handle is not leaked.
+//!         handle = unsafe { Handle::new(&data)? };
+//!
+//!         let _ = handle.wq.enqueue(handle.work.clone());
+//!     }
+//!     // Here the `compile_fail` is fulfilled as `handle` would be dropped
+//!     // after `data`.
+//!     Ok(())
+//! }
+//! ```
+
+use super::{
+    OwnedQueue,
+    Queue,
+    RawWorkItem, //
+};
+
+use crate::{
+    bindings,
+    ffi,
+    prelude::*, //
+};
+
+use core::marker::PhantomData;
+
+/// An owned workqueue that can enqueue work items borrowing from `'scope`.
+///
+/// A `ScopedQueue` must not outlive data borrowed by its work items.
+pub struct ScopedQueue<'scope> {
+    inner: OwnedQueue,
+    _scope: PhantomData<&'scope mut &'scope ()>,
+}
+

rust/kernel/workqueue/scoped.rs line 145

Quoted 10 lines
rust/kernel/workqueue/scoped.rs new file +10 -0
+impl<'scope> ScopedQueue<'scope> {
+    /// Creates an ordered scoped workqueue.
+    ///
+    /// # Safety
+    ///
+    /// The caller must not leak the returned queue or otherwise prevent its
+    /// [`Drop`] implementation from running since dropping the queue drains
+    /// pending and running work that may borrow from `'scope`.
+    #[inline]
+    pub unsafe fn new(name: &'static CStr) -> Result<Self> {

Does this really need to be ’static?

Quoted 48 lines
rust/kernel/workqueue/scoped.rs new file +45 -0
+        Ok(Self {
+            inner: Queue::new_ordered().build(name)?,
+            _scope: PhantomData,
+        })
+    }
+
+    /// Enqueues a work item on this scoped queue.
+    #[inline]
+    pub fn enqueue<W, const ID: u64>(&self, work: W) -> W::EnqueueOutput
+    where
+        W: RawWorkItem<ID> + Send + 'scope,
+    {
+        let queue_ptr = self.inner.0.get();
+
+        // SAFETY:
+        // - Closure returns `false` only if `queue_work_on` returns `false`
+        //   and that means `work_ptr` is already in a workqueue.
+        //
+        // - `W: 'scope` and dropck keep borrowed data alive until this queue is
+        //   dropped. The constructor requires that the queue is not leaked and
+        //   dropping `inner` drains pending and running work so the function
+        //   pointer is not called after any lifetime in `W` expires.
+        //
+        // - The last requirement of `__enqueue` is not relevant here because `W`
+        //   is `Send`.
+        unsafe {
+            work.__enqueue(move |work_ptr| {
+                bindings::queue_work_on(
+                    bindings::wq_misc_consts_WORK_CPU_UNBOUND as ffi::c_int,
+                    queue_ptr,
+                    work_ptr,
+                )
+            })
+        }
+    }
+}
+
+impl Drop for ScopedQueue<'_> {
+    #[inline]
+    fn drop(&mut self) {
+        // This impl makes dropck require `'scope` to outlive `OwnedQueue`.
+        // See: https://doc.rust-lang.org/nomicon/phantom-data.html#generic-parameters-and-drop-checking
+        let _ = &self._scope;
+    }
+}
Signature · 1 line
2.55.0

Would a conversion from OwnedQueue to ScopedQueue
make sense in the future?

#18 lore raw

Re: [PATCH v2 6/6] rust: workqueue: add ScopedWork for non-'static work items

In reply to Danilo Krummrich
Quoted 18 lines

/// Creates a [Work] initialiser with the given name and a newly-created lock class. #[macro_export]

rust/kernel/workqueue/mod.rs +8 -0
@@ -283,23 +289,39 @@ pub unsafe fn from_raw<'a>(ptr: *const bindings::workqueue_struct) -> &'a Queue
    /// This may fail if the work item is already enqueued in a workqueue.
    ///
    /// The work item will be submitted using `WORK_CPU_UNBOUND`.
+    #[inline]
    pub fn enqueue<W, const ID: u64>(&self, w: W) -> W::EnqueueOutput
    where
        W: RawWorkItem<ID> + Send + 'static,
+    {
+        // SAFETY: `W: 'static` guarantees the work item remains valid indefinitely,
+        // so the `enqueue_scoped` requirement that the work item stays valid until
+        // the work function runs (or is cancelled) is trivially satisfied.
+        unsafe { self.enqueue_scoped(w) }
+    }
+

rust/kernel/workqueue/mod.rs pub unsafe fn from_raw<'a>(ptr: *const bindings::workqueue_struct) -> &'a Queue · line 312

Quoted 10 lines
rust/kernel/workqueue/mod.rs +10 -0
+    /// Enqueues a work item that may not be `'static`.
+    ///
+    /// Unlike [`Queue::enqueue`], this does not require the work item to be `'static`.
+    ///
+    /// The work item will be submitted using `WORK_CPU_UNBOUND`.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that the work item's destructor runs before any
+    /// lifetime it captures expires (i.e., the work item must not be forgotten).

It seems like this requirement is due to cancel_work_sync(). But what happens if the item is enqueued with enqueue_scoped() on two work queues simultaneously? Would cancel_work_sync() wait for both queues?

Docs seem to warn against it, IIUC?

"Cancel work and wait for its execution to finish. This function can be used even if the work re-queues itself or migrates to another workqueue. On return from this function, work is guaranteed to be not pending or executing on any CPU —> as long as there aren’t racing enqueues. <—"

Quoted 5 lines
rust/kernel/workqueue/mod.rs +4 -0
+    #[inline]
+    pub unsafe fn enqueue_scoped<W, const ID: u64>(&self, w: W) -> W::EnqueueOutput
+    where
+        W: RawWorkItem<ID> + Send,
    {
maintainer
#14 lore raw

Re: [PATCH v2 5/6] rust: workqueue: add ScopedQueue for lifetime bound items

In reply to Danilo Krummrich
Quoted 18 lines · Danilo Krummrich

From: Onur Özkan <[email protected]>

Add a workqueue wrapper for work items that are not 'static.

Tyr reset work is queued from a handle that owns a Controller<'bound> where the work item holds references tied to the lifetime of the bound device and its mapped IO state. The existing API only accepts 'static work items which cannot express that relationship.

Introduce ScopedQueue for this case. It owns the underlying workqueue and ties enqueued work to the queue lifetime so borrowed state cannot outlive the queue that may still run it.

Construction is unsafe because the queue must not be leaked.

compile_fail doc-tests are ignored for now as KUnit doesn't support that. Enabling those tests as regular code block would raise this error:

Quoted 15 lines
    ERROR:root:error[E0597]: `data` does not live long enough
	 --> rust/doctests_kernel_generated.rs:22029:44
	  |
    22027 |         let data = ();
	  |             ---- binding `data` declared here
    22028 |         // SAFETY: Queue is not leaked.
    22029 |         queue = unsafe { new_queue(&data)? };
	  |                                            ^^^^^ borrowed value does not live long enough
    22030 |     }
	  |     - `data` dropped here while still borrowed
    ...
    22034 | }
	  | - borrow might be used here, when `queue` is dropped and runs the `Drop` code for type `ScopedQueue`
	  |
	  = note: values in a scope are dropped in the opposite order they are defined

The '^^^^^' on the warning doesn't quite point at the right location.

Quoted 158 lines

which is exactly the constraint ScopedQueue is meant to enforce.

[ Move from scoped_queue.rs to scoped.rs, which can be shared with
ScopedWork; add missing inline annotations. - Danilo ]

---
 rust/kernel/workqueue/mod.rs    |   3 +
 rust/kernel/workqueue/scoped.rs | 190 ++++++++++++++++++++++++++++++++
 2 files changed, 193 insertions(+)
 create mode 100644 rust/kernel/workqueue/scoped.rs
rust/kernel/workqueue/mod.rs +3 -0
index 8eb2d037be83..551fa1401b85 100644
@@ -212,6 +212,9 @@
 mod builder;
 pub use self::builder::Builder;
 
+mod scoped;
+pub use self::scoped::ScopedQueue;
+
 /// Creates a [`Work`] initialiser with the given name and a newly-created lock class.
 #[macro_export]
 macro_rules! new_work {
rust/kernel/workqueue/scoped.rs new file +124 -0
new file mode 100644
index 000000000000..18a4b6f6cf18
@@ -0,0 +1,190 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Lifetime-scoped workqueues.
+//!
+//! Provides [`ScopedQueue`] for work items that may borrow data with some
+//! non-`'static` lifetime.
+//!
+//! Unlike [`Queue`] which only accepts `'static` work items, [`ScopedQueue`]
+//! owns its underlying queue and relies on that queue being dropped to drain
+//! pending and running work before borrowed data can go out of scope.
+//!
+//! TODO: Remove `ignore` once KUnit supports `compile_fail` on doc-tests.
+//! ```compile_fail,ignore
+//! use kernel::prelude::*;
+//! use kernel::workqueue::ScopedQueue;
+//!
+//! /// # Safety
+//! ///
+//! /// Returned queue must not be leaked.
+//! unsafe fn new_queue<'bound>(_: &'bound ()) -> Result<ScopedQueue<'bound>> {
+//!     // SAFETY: Caller guarantees that the returned queue is not leaked.
+//!     unsafe { ScopedQueue::new(c"scoped_queue") }
+//! }
+//!
+//! fn queue_outlives_borrowed_data() -> Result {
+//!     let queue;
+//!
+//!     {
+//!         let data = ();
+//!         // SAFETY: Queue is not leaked.
+//!         queue = unsafe { new_queue(&data)? };
+//!     }
+//!     // Here the `compile_fail` is fulfilled as `queue` would be dropped
+//!     // after `data`.
+//!     Ok(())
+//! }
+//! ```
+//!
+//! TODO: Remove `ignore` once KUnit supports `compile_fail` on doc-tests.
+//! ```compile_fail,ignore
+//! use kernel::prelude::*;
+//! use kernel::sync::Arc;
+//! use kernel::workqueue::{
+//!     impl_has_work,
+//!     new_work,
+//!     ScopedQueue,
+//!     Work,
+//!     WorkItem,
+//! };
+//!
+//! #[pin_data]
+//! struct BorrowedWork<'bound> {
+//!     data: &'bound (),
+//!     #[pin]
+//!     work: Work<BorrowedWork<'bound>>,
+//! }
+//!
+//! impl_has_work! {
+//!     impl{'bound} HasWork<BorrowedWork<'bound>> for BorrowedWork<'bound> { self.work }
+//! }
+//!
+//! impl<'bound> WorkItem for BorrowedWork<'bound> {
+//!     type Pointer = Arc<Self>;
+//!
+//!     fn run(_this: Arc<Self>) {}
+//! }
+//!
+//! impl<'bound> BorrowedWork<'bound> {
+//!     fn new(data: &'bound ()) -> Result<Arc<Self>> {
+//!         Arc::pin_init(
+//!             pin_init!(Self {
+//!                 data,
+//!                 work <- new_work!("BorrowedWork::work"),
+//!             }),
+//!             GFP_KERNEL,
+//!         )
+//!     }
+//! }
+//!
+//! struct Handle<'bound> {
+//!     work: Arc<BorrowedWork<'bound>>,
+//!     wq: ScopedQueue<'bound>,
+//! }
+//!
+//! impl<'bound> Handle<'bound> {
+//!     /// # Safety
+//!     ///
+//!     /// Returned handle must not be leaked.
+//!     unsafe fn new(data: &'bound ()) -> Result<Self> {
+//!         Ok(Self {
+//!             work: BorrowedWork::new(data)?,
+//!             // SAFETY: Caller guarantees that the returned handle is not leaked.
+//!             wq: unsafe { ScopedQueue::new(c"handle_wq")? },
+//!         })
+//!     }
+//! }
+//!
+//! fn handle_outlives_borrowed_data() -> Result {
+//!     let handle;
+//!
+//!     {
+//!         let data = ();
+//!         // SAFETY: Handle is not leaked.
+//!         handle = unsafe { Handle::new(&data)? };
+//!
+//!         let _ = handle.wq.enqueue(handle.work.clone());
+//!     }
+//!     // Here the `compile_fail` is fulfilled as `handle` would be dropped
+//!     // after `data`.
+//!     Ok(())
+//! }
+//! ```
+
+use super::{
+    OwnedQueue,
+    Queue,
+    RawWorkItem, //
+};
+
+use crate::{
+    bindings,
+    ffi,
+    prelude::*, //
+};

rust/kernel/workqueue/scoped.rs line 134

Quoted 10 lines
rust/kernel/workqueue/scoped.rs new file +10 -0
+
+use core::marker::PhantomData;
+
+/// An owned workqueue that can enqueue work items borrowing from `'scope`.
+///
+/// A `ScopedQueue` must not outlive data borrowed by its work items.
+pub struct ScopedQueue<'scope> {
+    inner: OwnedQueue,
+    _scope: PhantomData<&'scope mut &'scope ()>,
+}

A Queue is the same as a ScopedQueue<'static>, so we don't necessarily need a new type if we add a lifetime to Queue and add two constructors:

	fn new() -> Queue<'static>;
	unsafe fn new_scoped() -> Queue<'a>;

Alice

maintainer
#19 lore raw

Re: [PATCH v2 6/6] rust: workqueue: add ScopedWork for non-'static work items

In reply to Danilo Krummrich
Quoted 23 lines · Danilo Krummrich

Add ScopedWork<T>, a work item wrapper whose destructor calls cancel_work_sync(), allowing T to carry non-'static lifetimes. Ownership of the data is not transferred to the workqueue; instead, the synchronous cancellation on drop guarantees the work function is not running when the data is freed.

ScopedWork uses the existing Work/HasWork/WorkItem infrastructure with NonNull<ScopedWorkRef<T>> as WorkItem::Pointer for the callback path, and implements RawWorkItem for &ScopedWork<T> and &ScopedWorkRef<T> for the enqueue path (requiring T: Sync for cross-thread shared access safety).

Two enqueue paths are provided:
- Queue::enqueue_scoped() (unsafe): the caller must ensure the work item is not forgotten.
- ScopedQueue::enqueue() (safe): when the work item's lifetime satisfies the queue's 'scope bound.

pub fn enqueue<W, const ID: u64>(&self, w: W) -> W::EnqueueOutput where
W: RawWorkItem<ID> + Send + 'static,
[...]

rust/kernel/workqueue/mod.rs pub unsafe fn from_raw<'a>(ptr: *const bindings::workqueue_struct) -> &'a Queue · line 316

Quoted 3 lines
rust/kernel/workqueue/mod.rs +3 -0
+    pub unsafe fn enqueue_scoped<W, const ID: u64>(&self, w: W) -> W::EnqueueOutput
+    where
+        W: RawWorkItem<ID> + Send,

I'm not convinced that enqueue_scoped() should be the unsafe operation. Rather, I think that should be the constructor of ScopedWork. If we promise to not forget it in ::new(), we can make this safe.

rust/kernel/workqueue/scoped.rs pub struct ScopedQueue<'scope> { · line 237

Quoted 8 lines
rust/kernel/workqueue/scoped.rs +8 -0
+impl Deref for ScopedQueue<'_> {
+    type Target = Queue;
+
+    #[inline]
+    fn deref(&self) -> &Queue {
+        &self.inner
+    }
+}

Should be part of previous patch.

rust/kernel/workqueue/scoped.rs fn drop(&mut self) { · line 293

Quoted 6 lines
rust/kernel/workqueue/scoped.rs +6 -0
+/// The work function's view of a [`ScopedWork`] item.
+///
+/// The work function callback receives `&ScopedWorkRef<T>`, which [`Deref`]s to `&T` and can be
+/// passed to queue enqueue methods for re-enqueueing from within the work function.
+#[pin_data]
+pub struct ScopedWorkRef<T: ScopedWorkItem> {

Structs with 'Ref' in their name sound like they are a reference/pointer, but this struct has no indirection.

rust/kernel/workqueue/scoped.rs fn drop(&mut self) { · line 324

Quoted 12 lines
rust/kernel/workqueue/scoped.rs +12 -0
+impl<T: ScopedWorkItem> WorkItem for ScopedWorkRef<T> {
+    type Pointer = NonNull<Self>;
+
+    #[inline]
+    fn run(this: NonNull<Self>) {
+        // SAFETY: `this` points to a valid, pinned `ScopedWorkRef`. `cancel_work_sync()` in
+        // `ScopedWork`'s `PinnedDrop` prevents use-after-drop.
+        let work = unsafe { &*this.as_ptr() };
+
+        T::run(work);
+    }
+}

This is unsound because its a safe function that dereferences a raw pointer.

I think you can avoid all of this logic by just not implementing WorkItem. You can skip all of that and just implement RawWorkItem for &ScopedWorkRef<T> and remove all the other implementations. You do not need the WorkItem impl.

Alice

maintainer
#20 lore raw

Re: [PATCH v2 6/6] rust: workqueue: add ScopedWork for non-'static work items

In reply to Danilo Krummrich
Quoted 26 lines · Danilo Krummrich

Add ScopedWork<T>, a work item wrapper whose destructor calls cancel_work_sync(), allowing T to carry non-'static lifetimes. Ownership of the data is not transferred to the workqueue; instead, the synchronous cancellation on drop guarantees the work function is not running when the data is freed.

ScopedWork uses the existing Work/HasWork/WorkItem infrastructure with NonNull<ScopedWorkRef<T>> as WorkItem::Pointer for the callback path, and implements RawWorkItem for &ScopedWork<T> and &ScopedWorkRef<T> for the enqueue path (requiring T: Sync for cross-thread shared access safety).

Two enqueue paths are provided:
- Queue::enqueue_scoped() (unsafe): the caller must ensure the work item is not forgotten.
- ScopedQueue::enqueue() (safe): when the work item's lifetime satisfies the queue's 'scope bound.

---
 rust/kernel/workqueue/mod.rs    |  46 +++-
 rust/kernel/workqueue/scoped.rs | 442 +++++++++++++++++++++++++++++---
 2 files changed, 444 insertions(+), 44 deletions(-)

[snip]

rust/kernel/workqueue/scoped.rs fn drop(&mut self) { · line 499

Quoted 10 lines
rust/kernel/workqueue/scoped.rs +10 -0
+impl<T: ScopedWorkItem> ScopedWork<T> {
+    /// Creates a pin-initializer for a new scoped work item.
+    ///
+    /// Use [`new_scoped_work!`] to automatically provide the lock class key.
+    #[inline]
+    pub fn new<E>(
+        name: &'static CStr,
+        key: Pin<&'static LockClassKey>,
+        init: impl PinInit<T, E>,
+    ) -> impl PinInit<Self, Error>

This should just propagate error and return E (you might need the ? E annotation for it).

rust/kernel/workqueue/scoped.rs fn drop(&mut self) { · line 510

Quoted 11 lines
rust/kernel/workqueue/scoped.rs +11 -0
+    where
+        Error: From<E>,
+    {
+        try_pin_init!(Self {
+            inner <- Opaque::pin_init(try_pin_init!(ScopedWorkRef::<T> {
+                work <- Work::new(name, key),
+                data <- init,
+            })),
+        })
+    }
+}

Best,
Gary

reviewer
#15 lore raw

Re: [PATCH v2 5/6] rust: workqueue: add ScopedQueue for lifetime bound items

In reply to Alice Ryhl
Quoted 209 lines · On Wed, 02 Sep 2026 14:40:51 +0000 Alice Ryhl <[email protected]> wrote:
Quoted 18 lines · Danilo Krummrich

From: Onur Özkan <[email protected]>

Add a workqueue wrapper for work items that are not 'static.

Tyr reset work is queued from a handle that owns a Controller<'bound> where the work item holds references tied to the lifetime of the bound device and its mapped IO state. The existing API only accepts 'static work items which cannot express that relationship.

Introduce ScopedQueue for this case. It owns the underlying workqueue and ties enqueued work to the queue lifetime so borrowed state cannot outlive the queue that may still run it.

Construction is unsafe because the queue must not be leaked.

compile_fail doc-tests are ignored for now as KUnit doesn't support that. Enabling those tests as regular code block would raise this error:

Quoted 15 lines
    ERROR:root:error[E0597]: `data` does not live long enough
	 --> rust/doctests_kernel_generated.rs:22029:44
	  |
    22027 |         let data = ();
	  |             ---- binding `data` declared here
    22028 |         // SAFETY: Queue is not leaked.
    22029 |         queue = unsafe { new_queue(&data)? };
	  |                                            ^^^^^ borrowed value does not live long enough
    22030 |     }
	  |     - `data` dropped here while still borrowed
    ...
    22034 | }
	  | - borrow might be used here, when `queue` is dropped and runs the `Drop` code for type `ScopedQueue`
	  |
	  = note: values in a scope are dropped in the opposite order they are defined

The '^^^^^' on the warning doesn't quite point at the right location.

Quoted 158 lines

which is exactly the constraint ScopedQueue is meant to enforce.

[ Move from scoped_queue.rs to scoped.rs, which can be shared with
ScopedWork; add missing inline annotations. - Danilo ]

---
 rust/kernel/workqueue/mod.rs    |   3 +
 rust/kernel/workqueue/scoped.rs | 190 ++++++++++++++++++++++++++++++++
 2 files changed, 193 insertions(+)
 create mode 100644 rust/kernel/workqueue/scoped.rs
rust/kernel/workqueue/mod.rs +3 -0
index 8eb2d037be83..551fa1401b85 100644
@@ -212,6 +212,9 @@
 mod builder;
 pub use self::builder::Builder;
 
+mod scoped;
+pub use self::scoped::ScopedQueue;
+
 /// Creates a [`Work`] initialiser with the given name and a newly-created lock class.
 #[macro_export]
 macro_rules! new_work {
rust/kernel/workqueue/scoped.rs new file +124 -0
new file mode 100644
index 000000000000..18a4b6f6cf18
@@ -0,0 +1,190 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Lifetime-scoped workqueues.
+//!
+//! Provides [`ScopedQueue`] for work items that may borrow data with some
+//! non-`'static` lifetime.
+//!
+//! Unlike [`Queue`] which only accepts `'static` work items, [`ScopedQueue`]
+//! owns its underlying queue and relies on that queue being dropped to drain
+//! pending and running work before borrowed data can go out of scope.
+//!
+//! TODO: Remove `ignore` once KUnit supports `compile_fail` on doc-tests.
+//! ```compile_fail,ignore
+//! use kernel::prelude::*;
+//! use kernel::workqueue::ScopedQueue;
+//!
+//! /// # Safety
+//! ///
+//! /// Returned queue must not be leaked.
+//! unsafe fn new_queue<'bound>(_: &'bound ()) -> Result<ScopedQueue<'bound>> {
+//!     // SAFETY: Caller guarantees that the returned queue is not leaked.
+//!     unsafe { ScopedQueue::new(c"scoped_queue") }
+//! }
+//!
+//! fn queue_outlives_borrowed_data() -> Result {
+//!     let queue;
+//!
+//!     {
+//!         let data = ();
+//!         // SAFETY: Queue is not leaked.
+//!         queue = unsafe { new_queue(&data)? };
+//!     }
+//!     // Here the `compile_fail` is fulfilled as `queue` would be dropped
+//!     // after `data`.
+//!     Ok(())
+//! }
+//! ```
+//!
+//! TODO: Remove `ignore` once KUnit supports `compile_fail` on doc-tests.
+//! ```compile_fail,ignore
+//! use kernel::prelude::*;
+//! use kernel::sync::Arc;
+//! use kernel::workqueue::{
+//!     impl_has_work,
+//!     new_work,
+//!     ScopedQueue,
+//!     Work,
+//!     WorkItem,
+//! };
+//!
+//! #[pin_data]
+//! struct BorrowedWork<'bound> {
+//!     data: &'bound (),
+//!     #[pin]
+//!     work: Work<BorrowedWork<'bound>>,
+//! }
+//!
+//! impl_has_work! {
+//!     impl{'bound} HasWork<BorrowedWork<'bound>> for BorrowedWork<'bound> { self.work }
+//! }
+//!
+//! impl<'bound> WorkItem for BorrowedWork<'bound> {
+//!     type Pointer = Arc<Self>;
+//!
+//!     fn run(_this: Arc<Self>) {}
+//! }
+//!
+//! impl<'bound> BorrowedWork<'bound> {
+//!     fn new(data: &'bound ()) -> Result<Arc<Self>> {
+//!         Arc::pin_init(
+//!             pin_init!(Self {
+//!                 data,
+//!                 work <- new_work!("BorrowedWork::work"),
+//!             }),
+//!             GFP_KERNEL,
+//!         )
+//!     }
+//! }
+//!
+//! struct Handle<'bound> {
+//!     work: Arc<BorrowedWork<'bound>>,
+//!     wq: ScopedQueue<'bound>,
+//! }
+//!
+//! impl<'bound> Handle<'bound> {
+//!     /// # Safety
+//!     ///
+//!     /// Returned handle must not be leaked.
+//!     unsafe fn new(data: &'bound ()) -> Result<Self> {
+//!         Ok(Self {
+//!             work: BorrowedWork::new(data)?,
+//!             // SAFETY: Caller guarantees that the returned handle is not leaked.
+//!             wq: unsafe { ScopedQueue::new(c"handle_wq")? },
+//!         })
+//!     }
+//! }
+//!
+//! fn handle_outlives_borrowed_data() -> Result {
+//!     let handle;
+//!
+//!     {
+//!         let data = ();
+//!         // SAFETY: Handle is not leaked.
+//!         handle = unsafe { Handle::new(&data)? };
+//!
+//!         let _ = handle.wq.enqueue(handle.work.clone());
+//!     }
+//!     // Here the `compile_fail` is fulfilled as `handle` would be dropped
+//!     // after `data`.
+//!     Ok(())
+//! }
+//! ```
+
+use super::{
+    OwnedQueue,
+    Queue,
+    RawWorkItem, //
+};
+
+use crate::{
+    bindings,
+    ffi,
+    prelude::*, //
+};

rust/kernel/workqueue/scoped.rs line 134

Quoted 10 lines
rust/kernel/workqueue/scoped.rs new file +10 -0
+
+use core::marker::PhantomData;
+
+/// An owned workqueue that can enqueue work items borrowing from `'scope`.
+///
+/// A `ScopedQueue` must not outlive data borrowed by its work items.
+pub struct ScopedQueue<'scope> {
+    inner: OwnedQueue,
+    _scope: PhantomData<&'scope mut &'scope ()>,
+}

A Queue is the same as a ScopedQueue<'static>, so we don't necessarily need a new type if we add a lifetime to Queue and add two constructors:

Quoted 2 lines
	fn new() -> Queue<'static>;
	unsafe fn new_scoped() -> Queue<'a>;

Sounds reasonable. Should I pull this series and do that approach directly on it, or send another version for [1]?

[1]: https://lore.kernel.org/all/[email protected]

Onur

Quoted 2 lines

Alice

reviewer
#13 lore raw

Re: [PATCH v2 5/6] rust: workqueue: add ScopedQueue for lifetime bound items

In reply to Daniel Almeida
Quoted 94 lines · On Thu, 27 Aug 2026 18:39:40 -0300 Daniel Almeida…
Quoted 81 lines · Danilo Krummrich

From: Onur Özkan <[email protected]>

Add a workqueue wrapper for work items that are not 'static.

Tyr reset work is queued from a handle that owns a Controller<'bound> where the work item holds references tied to the lifetime of the bound device and its mapped IO state. The existing API only accepts 'static work items which cannot express that relationship.

Introduce ScopedQueue for this case. It owns the underlying workqueue and ties enqueued work to the queue lifetime so borrowed state cannot outlive the queue that may still run it.

Construction is unsafe because the queue must not be leaked.

compile_fail doc-tests are ignored for now as KUnit doesn't support that. Enabling those tests as regular code block would raise this error:

ERROR:root:error[E0597]: data does not live long enough
--> rust/doctests_kernel_generated.rs:22029:44
|
22027 | let data = ();
| ---- binding data declared here

   22028 |         // SAFETY: Queue is not leaked.
   22029 |         queue = unsafe { new_queue(&data)? };

| ^^^^^ borrowed value does not live long enough
22030 | }
| - data dropped here while still borrowed
...
22034 | }
| - borrow might be used here, when queue is dropped and runs the Drop code for type ScopedQueue |
= note: values in a scope are dropped in the opposite order they are defined

which is exactly the constraint ScopedQueue is meant to enforce.

[ Move from scoped_queue.rs to scoped.rs, which can be shared with
ScopedWork; add missing inline annotations. - Danilo ]

---
rust/kernel/workqueue/mod.rs | 3 +
rust/kernel/workqueue/scoped.rs | 190 ++++++++++++++++++++++++++++++++

2 files changed, 193 insertions(+)

create mode 100644 rust/kernel/workqueue/scoped.rs

rust/kernel/workqueue/mod.rs +3 -0
index 8eb2d037be83..551fa1401b85 100644
@@ -212,6 +212,9 @@
 mod builder;
 pub use self::builder::Builder;
 
+mod scoped;
+pub use self::scoped::ScopedQueue;
+
 /// Creates a [`Work`] initialiser with the given name and a newly-created lock class.
 #[macro_export]
 macro_rules! new_work {
rust/kernel/workqueue/scoped.rs new file +10 -0
new file mode 100644
index 000000000000..18a4b6f6cf18
@@ -0,0 +1,190 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Lifetime-scoped workqueues.
+//!
+//! Provides [`ScopedQueue`] for work items that may borrow data with some
+//! non-`'static` lifetime.
+//!
+//! Unlike [`Queue`] which only accepts `'static` work items, [`ScopedQueue`]
+//! owns its underlying queue and relies on that queue being dropped to drain
+//! pending and running work before borrowed data can go out of scope.

rust/kernel/workqueue/scoped.rs line 20

Quoted 10 lines
rust/kernel/workqueue/scoped.rs new file +10 -0
+//!
+//! TODO: Remove `ignore` once KUnit supports `compile_fail` on doc-tests.
+//! ```compile_fail,ignore
+//! use kernel::prelude::*;
+//! use kernel::workqueue::ScopedQueue;
+//!
+//! /// # Safety
+//! ///
+//! /// Returned queue must not be leaked.
+//! unsafe fn new_queue<'bound>(_: &'bound ()) -> Result<ScopedQueue<'bound>> {

nit: is it me, or “bound” sounds out of place here? Perhaps ’scope instead?

Quoted 1 line

Same comment throughout the whole example.

We shouldn't use "bound" lifetime in this implementation. I will fix them in the next version.

Quoted 120 lines
Quoted 120 lines
rust/kernel/workqueue/scoped.rs new file +119 -0
+//!     // SAFETY: Caller guarantees that the returned queue is not leaked.
+//!     unsafe { ScopedQueue::new(c"scoped_queue") }
+//! }
+//!
+//! fn queue_outlives_borrowed_data() -> Result {
+//!     let queue;
+//!
+//!     {
+//!         let data = ();
+//!         // SAFETY: Queue is not leaked.
+//!         queue = unsafe { new_queue(&data)? };
+//!     }
+//!     // Here the `compile_fail` is fulfilled as `queue` would be dropped
+//!     // after `data`.
+//!     Ok(())
+//! }
+//! ```
+//!
+//! TODO: Remove `ignore` once KUnit supports `compile_fail` on doc-tests.
+//! ```compile_fail,ignore
+//! use kernel::prelude::*;
+//! use kernel::sync::Arc;
+//! use kernel::workqueue::{
+//!     impl_has_work,
+//!     new_work,
+//!     ScopedQueue,
+//!     Work,
+//!     WorkItem,
+//! };
+//!
+//! #[pin_data]
+//! struct BorrowedWork<'bound> {
+//!     data: &'bound (),
+//!     #[pin]
+//!     work: Work<BorrowedWork<'bound>>,
+//! }
+//!
+//! impl_has_work! {
+//!     impl{'bound} HasWork<BorrowedWork<'bound>> for BorrowedWork<'bound> { self.work }
+//! }
+//!
+//! impl<'bound> WorkItem for BorrowedWork<'bound> {
+//!     type Pointer = Arc<Self>;
+//!
+//!     fn run(_this: Arc<Self>) {}
+//! }
+//!
+//! impl<'bound> BorrowedWork<'bound> {
+//!     fn new(data: &'bound ()) -> Result<Arc<Self>> {
+//!         Arc::pin_init(
+//!             pin_init!(Self {
+//!                 data,
+//!                 work <- new_work!("BorrowedWork::work"),
+//!             }),
+//!             GFP_KERNEL,
+//!         )
+//!     }
+//! }
+//!
+//! struct Handle<'bound> {
+//!     work: Arc<BorrowedWork<'bound>>,
+//!     wq: ScopedQueue<'bound>,
+//! }
+//!
+//! impl<'bound> Handle<'bound> {
+//!     /// # Safety
+//!     ///
+//!     /// Returned handle must not be leaked.
+//!     unsafe fn new(data: &'bound ()) -> Result<Self> {
+//!         Ok(Self {
+//!             work: BorrowedWork::new(data)?,
+//!             // SAFETY: Caller guarantees that the returned handle is not leaked.
+//!             wq: unsafe { ScopedQueue::new(c"handle_wq")? },
+//!         })
+//!     }
+//! }
+//!
+//! fn handle_outlives_borrowed_data() -> Result {
+//!     let handle;
+//!
+//!     {
+//!         let data = ();
+//!         // SAFETY: Handle is not leaked.
+//!         handle = unsafe { Handle::new(&data)? };
+//!
+//!         let _ = handle.wq.enqueue(handle.work.clone());
+//!     }
+//!     // Here the `compile_fail` is fulfilled as `handle` would be dropped
+//!     // after `data`.
+//!     Ok(())
+//! }
+//! ```
+
+use super::{
+    OwnedQueue,
+    Queue,
+    RawWorkItem, //
+};
+
+use crate::{
+    bindings,
+    ffi,
+    prelude::*, //
+};
+
+use core::marker::PhantomData;
+
+/// An owned workqueue that can enqueue work items borrowing from `'scope`.
+///
+/// A `ScopedQueue` must not outlive data borrowed by its work items.
+pub struct ScopedQueue<'scope> {
+    inner: OwnedQueue,
+    _scope: PhantomData<&'scope mut &'scope ()>,
+}
+
+impl<'scope> ScopedQueue<'scope> {
+    /// Creates an ordered scoped workqueue.
+    ///
+    /// # Safety
Quoted 8 lines

rust/kernel/workqueue/scoped.rs line 145

Quoted 6 lines
rust/kernel/workqueue/scoped.rs new file +6 -0
+    ///
+    /// The caller must not leak the returned queue or otherwise prevent its
+    /// [`Drop`] implementation from running since dropping the queue drains
+    /// pending and running work that may borrow from `'scope`.
+    #[inline]
+    pub unsafe fn new(name: &'static CStr) -> Result<Self> {

Does this really need to be ’static?

It doesn't, will fix it in the next version.

Quoted 44 lines
Quoted 44 lines
rust/kernel/workqueue/scoped.rs new file +43 -0
+        Ok(Self {
+            inner: Queue::new_ordered().build(name)?,
+            _scope: PhantomData,
+        })
+    }
+
+    /// Enqueues a work item on this scoped queue.
+    #[inline]
+    pub fn enqueue<W, const ID: u64>(&self, work: W) -> W::EnqueueOutput
+    where
+        W: RawWorkItem<ID> + Send + 'scope,
+    {
+        let queue_ptr = self.inner.0.get();
+
+        // SAFETY:
+        // - Closure returns `false` only if `queue_work_on` returns `false`
+        //   and that means `work_ptr` is already in a workqueue.
+        //
+        // - `W: 'scope` and dropck keep borrowed data alive until this queue is
+        //   dropped. The constructor requires that the queue is not leaked and
+        //   dropping `inner` drains pending and running work so the function
+        //   pointer is not called after any lifetime in `W` expires.
+        //
+        // - The last requirement of `__enqueue` is not relevant here because `W`
+        //   is `Send`.
+        unsafe {
+            work.__enqueue(move |work_ptr| {
+                bindings::queue_work_on(
+                    bindings::wq_misc_consts_WORK_CPU_UNBOUND as ffi::c_int,
+                    queue_ptr,
+                    work_ptr,
+                )
+            })
+        }
+    }
+}
+
+impl Drop for ScopedQueue<'_> {
+    #[inline]
+    fn drop(&mut self) {
+        // This impl makes dropck require `'scope` to outlive `OwnedQueue`.
+        // See: https://doc.rust-lang.org/nomicon/phantom-data.html#generic-parameters-and-drop-checking
+        let _ = &self._scope;
Quoted 8 lines
Quoted 5 lines
rust/kernel/workqueue/scoped.rs new file +2 -0
+    }
+}
Signature · 1 line
2.55.0

Would a conversion from OwnedQueue to ScopedQueue
make sense in the future?

With Alice's suggestion [1], this wouldn't be needed.

[1]: https://lore.kernel.org/all/[email protected]

Onur

Quoted 2 lines