workqueue: OwnedQueue, ScopedQueue and ScopedWork
Subsystems (7)
Danilo Krummrich
maintainerv2 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.rsbase-commit: b48373c901951fad1a26bd7c33ad91172b3945b5
Signature · 1 line
2.55.0
Danilo Krummrich
maintainerPATCH 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
@@ -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
@@ -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
@@ -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
@@ -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
Danilo Krummrich
maintainerPATCH v2 2/6 rust: workqueue: restrict delayed work to global wqs
In reply to Danilo KrummrichFrom: 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
@@ -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
Danilo Krummrich
maintainerPATCH v2 3/6 rust: workqueue: create workqueue subdirectory
In reply to Danilo KrummrichFrom: 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
@@ -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
Signature · 1 line
2.55.0
Danilo Krummrich
maintainerPATCH v2 4/6 rust: workqueue: add creation of workqueues
In reply to Danilo KrummrichFrom: 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
@@ -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
Danilo Krummrich
maintainerPATCH v2 5/6 rust: workqueue: add ScopedQueue for lifetime bound items
In reply to Danilo KrummrichFrom: 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 definedwhich 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
@@ -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
Danilo Krummrich
maintainerPATCH v2 6/6 rust: workqueue: add ScopedWork for non-'static work items
In reply to Danilo KrummrichAdd 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
@@ -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
Danilo Krummrich
maintainerRe: [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+ } +}
Danilo Krummrich
maintainerRe: [PATCH v2 4/6] rust: workqueue: add creation of workqueues
In reply to Danilo KrummrichQuoted 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 ]---
Re: [PATCH v2 1/6] rust: workqueue: replace deprecated system_wq with system_{percpu,dfl}_wq
In reply to Danilo KrummrichRe: [PATCH v2 2/6] rust: workqueue: restrict delayed work to global wqs
In reply to Danilo KrummrichRe: [PATCH v2 3/6] rust: workqueue: create workqueue subdirectory
In reply to Danilo KrummrichDaniel Almeida
reviewerRe: [PATCH v2 4/6] rust: workqueue: add creation of workqueues
In reply to Danilo KrummrichQuoted 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 forWQ_POWER_EFFICIENT, in order to avoid the warning below.But I somehow managed to fix it the wrong way around and made
WQ_UNBOUNDthe 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?
Re: [PATCH v2 4/6] rust: workqueue: add creation of workqueues
In reply to Danilo KrummrichRe: [PATCH v2 5/6] rust: workqueue: add ScopedQueue for lifetime bound items
In reply to Danilo KrummrichQuoted 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_faildoc-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]:
datadoes not live long enough
-->rust/doctests_kernel_generated.rs:22029:44
|
22027 | let data = ();
| ---- bindingdatadeclared here22028 | // SAFETY: Queue is not leaked. 22029 | queue = unsafe { new_queue(&data)? };| ^^^^^ borrowed value does not live long enough
22030 | }
| -datadropped here while still borrowed
...
22034 | }
| - borrow might be used here, whenqueueis dropped and runs theDropcode for typeScopedQueue|
= note: values in a scope are dropped in the opposite order they are definedwhich is exactly the constraint ScopedQueue is meant to enforce.
Suggested-by Danilo Krummrich <[email protected]>Signed-off-by Onur Özkan <[email protected]>[ Move from
scoped_queue.rstoscoped.rs, which can be shared with
ScopedWork; add missing inline annotations. - Danilo ]Signed-off-by Danilo Krummrich <[email protected]>---
rust/kernel/workqueue/mod.rs| 3 +rust/kernel/workqueue/scoped.rs| 190 ++++++++++++++++++++++++++++++++2 files changed, 193 insertions(+)create mode 100644
rust/kernel/workqueue/scoped.rsrust/kernel/workqueue/mod.rs +3
-0@@ -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@@ -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 <&'scopemut &'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: &'staticCStr ) ->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_UNBOUNDas 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?
Daniel Almeida
reviewerRe: [PATCH v2 6/6] rust: workqueue: add ScopedWork for non-'static work items
In reply to Danilo KrummrichQuoted 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 , {
Alice Ryhl
maintainerRe: [PATCH v2 5/6] rust: workqueue: add ScopedQueue for lifetime bound items
In reply to Danilo KrummrichQuoted 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_faildoc-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 definedThe '^^^^^' on the warning doesn't quite point at the right location.
Quoted 158 lines
which is exactly the constraint ScopedQueue is meant to enforce.
Suggested-by Danilo Krummrich <[email protected]>Signed-off-by Onur Özkan <[email protected]>[ Move from
scoped_queue.rstoscoped.rs, which can be shared with
ScopedWork; add missing inline annotations. - Danilo ]Signed-off-by Danilo Krummrich <[email protected]>--- rust/kernel/workqueue/mod.rs | 3 + rust/kernel/workqueue/scoped.rs | 190 ++++++++++++++++++++++++++++++++ 2 files changed, 193 insertions(+) create mode 100644 rust/kernel/workqueue/scoped.rsrust/kernel/workqueue/mod.rs +3
-0@@ -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@@ -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 <&'scopemut &'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
Alice Ryhl
maintainerRe: [PATCH v2 6/6] rust: workqueue: add ScopedWork for non-'static work items
In reply to Danilo KrummrichQuoted 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::Pointerfor 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.Signed-off-by Danilo Krummrich <[email protected]>pub fn enqueue<W, const ID: u64>(&self, w: W) ->
W::EnqueueOutputwhere
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
Gary Guo
maintainerRe: [PATCH v2 6/6] rust: workqueue: add ScopedWork for non-'static work items
In reply to Danilo KrummrichQuoted 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::Pointerfor 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.Signed-off-by Danilo Krummrich <[email protected]>--- 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: &'staticCStr , + key:Pin <&'staticLockClassKey >, + 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
Onur Özkan
reviewerRe: [PATCH v2 5/6] rust: workqueue: add ScopedQueue for lifetime bound items
In reply to Alice RyhlQuoted 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_faildoc-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 definedThe '^^^^^' on the warning doesn't quite point at the right location.
Quoted 158 lines
which is exactly the constraint ScopedQueue is meant to enforce.
Suggested-by Danilo Krummrich <[email protected]>Signed-off-by Onur Özkan <[email protected]>[ Move from
scoped_queue.rstoscoped.rs, which can be shared with
ScopedWork; add missing inline annotations. - Danilo ]Signed-off-by Danilo Krummrich <[email protected]>--- rust/kernel/workqueue/mod.rs | 3 + rust/kernel/workqueue/scoped.rs | 190 ++++++++++++++++++++++++++++++++ 2 files changed, 193 insertions(+) create mode 100644 rust/kernel/workqueue/scoped.rsrust/kernel/workqueue/mod.rs +3
-0@@ -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@@ -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 <&'scopemut &'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
Onur Özkan
reviewerRe: [PATCH v2 5/6] rust: workqueue: add ScopedQueue for lifetime bound items
In reply to Daniel AlmeidaQuoted 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_faildoc-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]:
datadoes not live long enough
-->rust/doctests_kernel_generated.rs:22029:44
|
22027 | let data = ();
| ---- bindingdatadeclared here22028 | // SAFETY: Queue is not leaked. 22029 | queue = unsafe { new_queue(&data)? };| ^^^^^ borrowed value does not live long enough
22030 | }
| -datadropped here while still borrowed
...
22034 | }
| - borrow might be used here, whenqueueis dropped and runs theDropcode for typeScopedQueue|
= note: values in a scope are dropped in the opposite order they are definedwhich is exactly the constraint ScopedQueue is meant to enforce.
Suggested-by Danilo Krummrich <[email protected]>Signed-off-by Onur Özkan <[email protected]>[ Move from
scoped_queue.rstoscoped.rs, which can be shared with
ScopedWork; add missing inline annotations. - Danilo ]Signed-off-by Danilo Krummrich <[email protected]>---
rust/kernel/workqueue/mod.rs| 3 +rust/kernel/workqueue/scoped.rs| 190 ++++++++++++++++++++++++++++++++2 files changed, 193 insertions(+)create mode 100644
rust/kernel/workqueue/scoped.rsrust/kernel/workqueue/mod.rs +3
-0@@ -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@@ -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 <&'scopemut &'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: &'staticCStr ) ->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_UNBOUNDas 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.0Would 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
Reviewed-by Daniel Almeida <[email protected]>