workqueue: rust: add work item runtime modification support
PATCH 1/1 workqueue: rust: add work item runtime modification support
This feature is required for our Hyper-V VMBus reimplementation effort. As it provides the ability to modify the running state of work items at runtime.
The design revolves around having Queue::enqueue()/Queue::enqueue_delayed() return implementations of WorkHandle which can then be used to enable/disable/cancel the relevant work item.
Please see the example introduced at the top of the file for example usage of work handles.
--- rust/kernel/workqueue.rs | 239 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 233 insertions(+), 6 deletions(-)
rust/kernel/workqueue.rs +233 -6
@@ -135,7 +135,7 @@//! //! ``` //! use kernel::sync::Arc; -//! use kernel::workqueue::{self, impl_has_delayed_work, new_delayed_work, DelayedWork, WorkItem}; +//! use kernel::workqueue::{self, impl_has_delayed_work, new_delayed_work, DelayedWork, WorkItem, WorkHandle}; //! //! #[pin_data] //! struct MyStruct {
@@ -179,8 +179,22 @@//! fn print_now(val: Arc<MyStruct>) { //! let _ = workqueue::system().enqueue(val); //! } +//! +//! /// The returned WorkHandle can be used to cancel the work item before it gets executed. +//! fn print_never(val: Arc<MyStruct>) { +//! let result = workqueue::system_bh().enqueue_delayed(val, 1000); +//! +//! match result { +//! Ok(handle) => { +//! handle.cancel(true); +//! }, +//! Err(_) => (), +//! } +//! } +//! //! # print_later(MyStruct::new(42).unwrap()); //! # print_now(MyStruct::new(42).unwrap()); +//! # print_never(MyStruct::new(42).unwrap()); //! ``` //! //! C header: [`include/linux/workqueue.h`](srctree/include/linux/workqueue.h)
@@ -297,7 +311,7 @@ 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. /// /// 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 >(&self, w:W , delay:Jiffies ) ->W ::EnqueueDelayedOutput where W :RawDelayedWorkItem <ID > +Send + 'static, {
@@ -317,7 +331,7 @@ pub fn enqueue_delayed<W, const ID: u64>(&self, w: W, delay: Jiffies) -> W::Enqu// promises that the raw pointer will stay valid until we call the function pointer in the // `work_struct`, so the access is ok. unsafe { - w.__enqueue (move |work_ptr| { + w.__enqueue_delayed (move |work_ptr| { bindings::queue_delayed_work_on ( bindings::wq_misc_consts_WORK_CPU_UNBOUNDas ffi::c_int , queue_ptr,
@@ -421,7 +435,15 @@ unsafe fn __enqueue<F>(self, queue_work_on: F) -> Self::EnqueueOutput/// provided pointer must point at the `work` field of a valid `delayed_work`, and the guarantees /// that `__enqueue` provides about accessing the `work_struct` must also apply to the rest of the /// `delayed_work` struct. -pub unsafe trait RawDelayedWorkItem <const ID :u64 >:RawWorkItem <ID > {} +pub unsafe trait RawDelayedWorkItem <const ID :u64 >:RawWorkItem <ID > { +/// The return type of [`Queue::enqueue_delayed`]. +type EnqueueDelayedOutput ; + +/// See [`RawWorkItem::__enqueue`], this method only differs in return type. +unsafe fn __enqueue_delayed <F >(self, queue_work_on:F ) ->Self ::EnqueueDelayedOutput +where +F :FnOnce (*mut bindings::work_struct ) ->bool ; +}/// Defines the method that should be called directly when a work item is executed. ///
@@ -530,6 +552,66 @@ pub unsafe fn raw_get(ptr: *const Self) -> *mut bindings::work_struct {// the compiler does not complain that the `work` field is unused. unsafe {Opaque ::cast_into (core::ptr::addr_of!((*ptr).work)) } } + +/// Enable the current work item +#[inline] +pub unsafe fn raw_enable (this: *const Self ) ->bool { +unsafe { bindings::enable_work (Self ::raw_get (this)) } + } + +/// Disable and cancel the current work item +#[inline] +pub unsafe fn raw_disable (this: *const Self ) ->bool { +unsafe { bindings::disable_work (Self ::raw_get (this)) } + } + +#[inline] +unsafe fn raw_get_delayed (this: *const Self ) -> *mut bindings::delayed_work { +let work_ptr =unsafe {Self ::raw_get (this) }; +unsafe {container_of! (work_ptr, bindings::delayed_work, work) } + } + +/// Disable and cancel the current delayed work item +#[inline] +pub unsafe fn raw_disable_delayed (this: *const Self ) ->bool { +unsafe { bindings::disable_delayed_work (Self ::raw_get_delayed (this)) } + } + +/// Disable and cancel the current work item and block until it's done +#[inline] +pub unsafe fn raw_disable_sync (this: *const Self ) ->bool { +unsafe { bindings::disable_work_sync (Self ::raw_get (this)) } + } + +/// Disable and cancel the current delayed work item and block until it's done +#[inline] +pub unsafe fn raw_disable_delayed_sync (this: *const Self ) ->bool { +unsafe { bindings::disable_delayed_work_sync (Self ::raw_get_delayed (this)) } + } + +/// Kill off the current work item +#[inline] +pub unsafe fn raw_cancel (this: *const Self ) ->bool { +unsafe { bindings::cancel_work (Self ::raw_get (this)) } + } + +/// Kill off the current delayed work item +#[inline] +pub unsafe fn raw_cancel_delayed (this: *const Self ) ->bool { +unsafe { bindings::cancel_delayed_work (Self ::raw_get_delayed (this)) } + } + +/// Kill off the current work item and block until it's done +#[inline] +pub unsafe fn raw_cancel_sync (this: *const Self ) ->bool { +unsafe { bindings::cancel_work_sync (Self ::raw_get (this)) } + } + +/// Kill off the current delayed work item and block until it's done +#[inline] +pub unsafe fn raw_cancel_delayed_sync (this: *const Self ) ->bool { +unsafe { bindings::cancel_delayed_work_sync (Self ::raw_get_delayed (this)) } + } }/// Declares that a type contains a [`Work<T, ID>`].
@@ -578,6 +660,122 @@ pub unsafe trait HasWork<T, const ID: u64 = 0> {unsafe fn work_container_of (ptr: *mut Work <T ,ID >) -> *mut Self ; } +/// A handle representing a potentially running work item. +pub unsafe trait WorkHandle { +/// Enable a work item +/// +/// SAFETY: can be called from any context. +/// +/// Returns `true` only if the disable count reached 0. +fn enable (self) ->bool ; + +/// Disable and cancel a work item +/// +/// SAFETY: Can be called from any context if `sync` is set to `false`. +/// +/// If `sync` is set to true this method will block until the work item +/// has been cancelled. +/// +/// Returns `true` if the work item was pending. +fn disable (self, sync:bool ) ->bool ; + +/// Cancel a work item +/// +/// SAFETY: Can be called from any context if `sync` is set to `false`. +/// +/// If `sync` is set to true this method will block until the work item +/// has been cancelled. +/// +/// Returns `true` if the work item was pending. +fn cancel (self, sync:bool ) ->bool ; +} + +/// A handle for an `Arc<HasWork<T>>` returned by a call to +/// [`RawWorkItem::__enqueue`] +pub struct ArcWorkHandle <T ,const ID :u64 =0 > +where +T :HasWork <T ,ID >, +{ + inner:Arc <T >, +} + +unsafe impl <T ,const ID :u64 >WorkHandle for ArcWorkHandle <T ,ID > +where +T :HasWork <T ,ID >, +{ +fn enable (self) ->bool { +let self_ptr =Arc ::as_ptr (&self.inner)as *mut T ; +let work_ptr =unsafe { <T as HasWork <T ,ID >>::raw_get_work (self_ptr) }; + +unsafe {Work ::<T ,ID >::raw_enable (work_ptr) } + } + +fn disable (self, sync:bool ) ->bool { +let self_ptr =Arc ::as_ptr (&self.inner)as *mut T ; +let work_ptr =unsafe { <T as HasWork <T ,ID >>::raw_get_work (self_ptr) }; + +if sync { +unsafe {Work ::<T ,ID >::raw_disable_sync (work_ptr) } + }else { +unsafe {Work ::<T ,ID >::raw_disable (work_ptr) } + } + } + +fn cancel (self, sync:bool ) ->bool { +let self_ptr =Arc ::as_ptr (&self.inner)as *mut T ; +let work_ptr =unsafe { <T as HasWork <T ,ID >>::raw_get_work (self_ptr) }; + +if sync { +unsafe {Work ::<T ,ID >::raw_cancel_sync (work_ptr) } + }else { +unsafe {Work ::<T ,ID >::raw_cancel (work_ptr) } + } + } +} + +/// A handle for an `Arc<HasDelayedWork<T>>` returned by a call to +/// [`RawWorkItem::__enqueue_delayed`] +pub struct ArcDelayedWorkHandle <T ,const ID :u64 =0 > +where +T :HasDelayedWork <T ,ID >, +{ + inner:Arc <T >, +} + +unsafe impl <T ,const ID :u64 >WorkHandle for ArcDelayedWorkHandle <T ,ID > +where +T :HasDelayedWork <T ,ID >, +{ +fn enable (self) ->bool { +let self_ptr =Arc ::as_ptr (&self.inner)as *mut T ; +let work_ptr =unsafe { <T as HasWork <T ,ID >>::raw_get_work (self_ptr) }; + +unsafe {Work ::<T ,ID >::raw_enable (work_ptr) } + } + +fn disable (self, sync:bool ) ->bool { +let self_ptr =Arc ::as_ptr (&self.inner)as *mut T ; +let work_ptr =unsafe { <T as HasWork <T ,ID >>::raw_get_work (self_ptr) }; + +if sync { +unsafe {Work ::<T ,ID >::raw_disable_delayed_sync (work_ptr) } + }else { +unsafe {Work ::<T ,ID >::raw_disable_delayed (work_ptr) } + } + } + +fn cancel (self, sync:bool ) ->bool { +let self_ptr =Arc ::as_ptr (&self.inner)as *mut T ; +let work_ptr =unsafe { <T as HasWork <T ,ID >>::raw_get_work (self_ptr) }; + +if sync { +unsafe {Work ::<T ,ID >::raw_cancel_delayed_sync (work_ptr) } + }else { +unsafe {Work ::<T ,ID >::raw_cancel_delayed (work_ptr) } + } + } +} +/// Used to safely implement the [`HasWork<T, ID>`] trait. /// /// # Examples
@@ -841,7 +1039,7 @@ unsafe impl<T, const ID: u64> RawWorkItem<ID> for Arc<T> T: WorkItem<ID, Pointer = Self>, T: HasWork<T, ID>, { -type EnqueueOutput =Result <(),Self >; +type EnqueueOutput =Result <ArcWorkHandle <T ,ID >,Self >;unsafe fn __enqueue <F >(self, queue_work_on:F ) ->Self ::EnqueueOutput where
@@ -856,7 +1054,7 @@ unsafe fn __enqueue<F>(self, queue_work_on: F) -> Self::EnqueueOutputlet work_ptr =unsafe {Work ::raw_get (work_ptr) };if queue_work_on (work_ptr) { -Ok (()) +Ok (ArcWorkHandle { inner:unsafe {Arc ::from_raw (ptr) } }) }else {// SAFETY: The work queue has not taken ownership of the pointer. Err (unsafe {Arc ::from_raw (ptr) })
@@ -872,6 +1070,27 @@ unsafe impl<T, const ID: u64> RawDelayedWorkItem<ID> for Arc<T> T: WorkItem<ID, Pointer = Self>, T: HasDelayedWork<T, ID>, { +type EnqueueDelayedOutput =Result <ArcDelayedWorkHandle <T ,ID >,Self >; + +unsafe fn __enqueue_delayed <F >(self, queue_work_on:F ) ->Self ::EnqueueDelayedOutput +where +F :FnOnce (*mut bindings::work_struct ) ->bool , + { +// Casting between const and mut is not a problem as long as the pointer is a raw pointer. +let ptr =Arc ::into_raw (self).cast_mut (); + +// SAFETY: Pointers into an `Arc` point at a valid value. +let work_ptr =unsafe {T ::raw_get_work (ptr) }; +// SAFETY: `raw_get_work` returns a pointer to a valid value. +let work_ptr =unsafe {Work ::raw_get (work_ptr) }; + +if queue_work_on (work_ptr) { +Ok (ArcDelayedWorkHandle { inner:unsafe {Arc ::from_raw (ptr) } }) + }else { +// SAFETY: The work queue has not taken ownership of the pointer. +Err (unsafe {Arc ::from_raw (ptr) }) + } + } }// SAFETY: TODO.
@@ -932,6 +1151,14 @@ unsafe impl<T, const ID: u64> RawDelayedWorkItem<ID> for Pin<KBox<T>> T: WorkItem<ID, Pointer = Self>, T: HasDelayedWork<T, ID>, { +type EnqueueDelayedOutput = (); + +unsafe fn __enqueue_delayed <F >(self, queue_work_on:F ) ->Self ::EnqueueDelayedOutput +where +F :FnOnce (*mut bindings::work_struct ) ->bool , + { +unsafe { self.__enqueue (queue_work_on) } + } }/// Returns the system work queue (`system_wq`).
Signature · 1 line
2.52.0
kernel test robot
build botkernel test robot noticed the following build warnings:
Hi Hamza,
kernel test robot noticed the following build warnings:
[auto build test WARNING on rust/rust-next]
[also build test WARNING on next-20260203]
[cannot apply to linus/master v6.16-rc1]
[If your patch is applied to the wrong git tree, kindly drop us a note. And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]
url: https://github.com/intel-lab-lkp/linux/commits/Hamza-Mahfooz/workqueue-rust-add-work-item-runtime-modification-support/20260204-060728 base: https://github.com/Rust-for-Linux/linux rust-next patch link: https://lore.kernel.org/r/20260203215555.832171-1-hamzamahfooz%40linux.microsoft.com patch subject: [PATCH] workqueue: rust: add work item runtime modification support config: x86_64-rhel-9.4-rust (https://download.01.org/0day-ci/archive/20260204/[email protected]/config) compiler: clang version 20.1.8 (https://github.com/llvm/llvm-project 87f0227cb60147a26a1eeb4fb06e3b505e9c7261) rustc: rustc 1.88.0 (6b00bc388 2025-06-23) reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20260204/[email protected]/reproduce)
If you fix the issue in a separate patch/commit (i.e. not just a new version of the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <[email protected]>
| Closes: https://lore.kernel.org/oe-kbuild-all/[email protected]/
All warnings (new ones prefixed by >>):
>> warning: unsafe function's docs are missing a `# Safety` section --> rust/kernel/workqueue.rs:443:5 | 443 | / unsafe fn __enqueue_delayed<F>(self, queue_work_on: F) -> Self::EnqueueDelayedOutput 444 | | where 445 | | F: FnOnce(*mut bindings::work_struct) -> bool; | |______________________________________________________^ |
= help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#missing_safety_doc
= note: -W clippy::missing-safety-doc implied by -W clippy::all
= help: to override -W clippy::all add #[allow(clippy::missing_safety_doc)]
--
>> warning: unsafe function's docs are missing a `# Safety` section
--> rust/kernel/workqueue.rs:558:5
|
558 | pub unsafe fn raw_enable(this: *const Self) -> bool {
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
= help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#missing_safety_doc
--
>> warning: unsafe function's docs are missing a `# Safety` section
--> rust/kernel/workqueue.rs:582:5
|
582 | pub unsafe fn raw_disable_sync(this: *const Self) -> bool {
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
= help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#missing_safety_doc
--
>> warning: unsafe function's docs are missing a `# Safety` section
--> rust/kernel/workqueue.rs:588:5
|
588 | pub unsafe fn raw_disable_delayed_sync(this: *const Self) -> bool {
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
= help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#missing_safety_doc
--
>> warning: unsafe function's docs are missing a `# Safety` section
--> rust/kernel/workqueue.rs:594:5
|
594 | pub unsafe fn raw_cancel(this: *const Self) -> bool {
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
= help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#missing_safety_doc
--
>> warning: unsafe function's docs are missing a `# Safety` section
--> rust/kernel/workqueue.rs:600:5
|
600 | pub unsafe fn raw_cancel_delayed(this: *const Self) -> bool {
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
= help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#missing_safety_doc
--
>> warning: unsafe function's docs are missing a `# Safety` section
--> rust/kernel/workqueue.rs:606:5
|
606 | pub unsafe fn raw_cancel_sync(this: *const Self) -> bool {
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
= help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#missing_safety_doc
--
>> warning: unsafe function's docs are missing a `# Safety` section
--> rust/kernel/workqueue.rs:612:5
|
612 | pub unsafe fn raw_cancel_delayed_sync(this: *const Self) -> bool {
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
= help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#missing_safety_doc
--
>> warning: docs for unsafe trait missing `# Safety` section
--> rust/kernel/workqueue.rs:664:1
|
664 | pub unsafe trait WorkHandle {
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
= help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#missing_safety_doc
--
>> warning: unsafe impl missing a safety comment
--> rust/kernel/workqueue.rs:702:1
|
702 | unsafe impl<T, const ID: u64> WorkHandle for ArcWorkHandle<T, ID>
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
= help: consider adding a safety comment on the preceding line
= help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#undocumented_unsafe_blocks
--
>> warning: unsafe function's docs are missing a `# Safety` section
--> rust/kernel/workqueue.rs:564:5
|
564 | pub unsafe fn raw_disable(this: *const Self) -> bool {
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
= help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#missing_safety_doc
..
Signature · 2 lines
0-DAY CI Kernel Test Service https://github.com/intel/lkp-tests/wiki
Quoted 3 lines · Hamza Mahfooz
This feature is required for our Hyper-V VMBus reimplementation effort. As it provides the ability to modify the running state of work items at runtime.
This is great, BUT we need to see the user of this new code at the same time before adding it to the kernel tree. Why not just submit this as part of your patch series for the rust hyperv stuff?
thanks,
greg k-h
Quoted 8 lines · Greg KH
Quoted 3 lines · Hamza Mahfooz
This feature is required for our Hyper-V VMBus reimplementation effort. As it provides the ability to modify the running state of work items at runtime.
This is great, BUT we need to see the user of this new code at the same time before adding it to the kernel tree. Why not just submit this as part of your patch series for the rust hyperv stuff?
I don't have the rest fully fleshed out quite yet. So, mostly just working on getting the prerequistes in a good state. I can mark it as an RFC if that is preferable.
Quoted 4 lines
thanks,
greg k-h
Quoted 6 lines · Hamza Mahfooz
Quoted 5 lines · Greg KH
Quoted 3 lines · Hamza Mahfooz
This feature is required for our Hyper-V VMBus reimplementation effort. As it provides the ability to modify the running state of work items at runtime.
Quoted 7 lines
Quoted 3 lines
This is great, BUT we need to see the user of this new code at the same time before adding it to the kernel tree. Why not just submit this as part of your patch series for the rust hyperv stuff?
I don't have the rest fully fleshed out quite yet. So, mostly just working on getting the prerequistes in a good state. I can mark it as an RFC if that is preferable.
Just send it all when you feel it is ready, no need to ask us to review an api when you don't even have working code that uses it for you to determine if it works or not :)
thanks,
greg k-h