3 //! Work queues.
5 //! This file has two components: The raw work item API, and the safe work item API.
15 //! The raw API consists of the [`RawWorkItem`] trait, where the work item needs to provide an
16 //! arbitrary function that knows how to enqueue the work item. It should usually not be used
21 //! The safe API is used via the [`Work`] struct and [`WorkItem`] traits. Furthermore, it also
24 //!  * The [`Work`] struct is the Rust wrapper for the C `work_struct` type.
37 //! use kernel::workqueue::{self, impl_has_work, new_work, Work, WorkItem};
43 //!     work: Work<MyStruct>,
47 //!     impl HasWork<Self> for MyStruct { self.work }
54 //!             work <- new_work!("MyStruct::work"),
79 //! use kernel::workqueue::{self, impl_has_work, new_work, Work, WorkItem};
86 //!     work_1: Work<MyStruct, 1>,
88 //!     work_2: Work<MyStruct, 2>,
134 //! This example shows how you can schedule delayed work items:
144 //!     work: DelayedWork<MyStruct>,
148 //!     impl HasDelayedWork<Self> for MyStruct { self.work }
156 //!                 work <- new_delayed_work!("MyStruct::work"),
199 /// Creates a [`Work`] initialiser with the given name and a newly-created lock class.
203 …      $crate::workqueue::Work::new($crate::optional_name!($($name)?), $crate::static_lock_class!())
235 /// A kernel work queue.
239 /// It allows work items to be queued to run on thread pools managed by the kernel. Several are
262     /// Enqueues a work item.
264     /// This may fail if the work item is already enqueued in a workqueue.
266     /// The work item will be submitted using `WORK_CPU_UNBOUND`.
281         // `__enqueue`, then the work item was successfully enqueued, and `bindings::queue_work_on`  in enqueue()
295     /// Enqueues a delayed work item.
297     /// This may fail if the work item is already enqueued in a workqueue.
299     /// The work item will be submitted using `WORK_CPU_UNBOUND`.
315         // `__enqueue`, then the work item was successfully enqueued, and  in enqueue_delayed()
324                     container_of!(work_ptr, bindings::delayed_work, work),  in enqueue_delayed()
331     /// Tries to spawn the given function or closure as a work item.
333     /// This method can fail because it allocates memory to store the work item.
340             work <- new_work!("Queue::try_spawn"),  in try_spawn()
355     work: Work<ClosureWork<T>>,  field
369 /// A raw work item.
393     /// Enqueues this work item on a queue using the provided `queue_work_on` method.
406     /// If the work item type is annotated with any lifetimes, then you must not call the function
409     /// If the work item type is not [`Send`], then the function pointer must be called on the same
416 /// A raw delayed work item.
421 /// provided pointer must point at the `work` field of a valid `delayed_work`, and the guarantees
426 /// Defines the method that should be called directly when a work item is executed.
434 /// This trait is used when the `work_struct` field is defined using the [`Work`] helper.
444     /// Run this work item.
455 /// Defines the method that should be called when this work item is executed.
457 /// This trait is used when the `work_struct` field is defined using the [`Work`] helper.
463     /// The method that should be called when this work item is executed.
467 /// Links for a work item.
470 /// trait, and defines the linked list pointers necessary to enqueue a work item in a workqueue.
479 pub struct Work<T: ?Sized, const ID: u64 = 0> {  struct
481     work: Opaque<bindings::work_struct>,  field
485 // SAFETY: Kernel work items are usable from any thread.
487 // We do not need to constrain `T` since the work item does not actually contain a `T`.
488 unsafe impl<T: ?Sized, const ID: u64> Send for Work<T, ID> {}  argument
489 // SAFETY: Kernel work items are usable from any thread.
491 // We do not need to constrain `T` since the work item does not actually contain a `T`.
492 unsafe impl<T: ?Sized, const ID: u64> Sync for Work<T, ID> {}  implementation
494 impl<T: ?Sized, const ID: u64> Work<T, ID> {  impl
495     /// Creates a new instance of [`Work`].
502             work <- Opaque::ffi_init(|slot| {  in new()
504                 // the work item function.  in new()
530         // the compiler does not complain that the `work` field is unused.  in raw_get()
531         unsafe { Opaque::cast_into(core::ptr::addr_of!((*ptr).work)) }  in raw_get()
535 /// Declares that a type contains a [`Work<T, ID>`].
541 /// use kernel::workqueue::{impl_has_work, Work};
544 ///     work_field: Work<MyWorkItem, 1>,
552 /// Note that since the [`Work`] type is annotated with an id, you can have several `work_struct`
560 /// - `raw_get_work(work_container_of(ptr)) == ptr` for any `ptr: *mut Work<T, ID>`.
566     /// Returns a pointer to the [`Work<T, ID>`] field.
571     unsafe fn raw_get_work(ptr: *mut Self) -> *mut Work<T, ID>;  in raw_get_work()
573     /// Returns a pointer to the struct containing the [`Work<T, ID>`] field.
577     /// The pointer must point at a [`Work<T, ID>`] field in a struct of type `Self`.
578     unsafe fn work_container_of(ptr: *mut Work<T, ID>) -> *mut Self;  in work_container_of()
587 /// use kernel::workqueue::{self, impl_has_work, Work};
590 ///     work_field: Work<MyStruct<'a, T, N>, 17>,
610 …     unsafe fn raw_get_work(ptr: *mut Self) -> *mut $crate::workqueue::Work<$work_type $(, $id)?> {
619                 ptr: *mut $crate::workqueue::Work<$work_type $(, $id)?>,
631     impl{T} HasWork<Self> for ClosureWork<T> { self.work }
634 /// Links for a delayed work item.
637 /// trait, and defines the linked list pointers necessary to enqueue a work item in a workqueue in
653 // SAFETY: Kernel work items are usable from any thread.
655 // We do not need to constrain `T` since the work item does not actually contain a `T`.
657 // SAFETY: Kernel work items are usable from any thread.
659 // We do not need to constrain `T` since the work item does not actually contain a `T`.
677                 // the work item function.  in new()
680                         core::ptr::addr_of_mut!((*slot).work),  in new()
712     pub unsafe fn raw_as_work(ptr: *const Self) -> *mut Work<T, ID> {  in raw_as_work()
717         let wrk: *mut bindings::work_struct = unsafe { core::ptr::addr_of_mut!((*dw).work) };  in raw_as_work()
718         // CAST: Work and work_struct have compatible layouts.  in raw_as_work()
727 /// The `HasWork<T, ID>` implementation must return a `work_struct` that is stored in the `work`
770             ) -> *mut $crate::workqueue::Work<$work_type $(, $id)?> {
782                 ptr: *mut $crate::workqueue::Work<$work_type $(, $id)?>,
786                 let ptr = unsafe { $crate::workqueue::Work::raw_get(ptr) };
791                     $crate::container_of!(ptr, $crate::bindings::delayed_work, work)
808 //   - `__enqueue` gets the `work_struct` from the `Work` field, using `T::raw_get_work`.
809 //   - The only safe way to create a `Work` object is through `Work::new`.
810 //   - `Work::new` makes sure that `T::Pointer::run` is passed to `init_work_with_key`.
811 //   - Finally `Work` and `RawWorkItem` guarantee that the correct `Work` field
813 //     uses the correct offset for the `Work` field, and `Work::new` picks the correct
821         // The `__enqueue` method always uses a `work_struct` stored in a `Work<T, ID>`.  in run()
822         let ptr = ptr.cast::<Work<T, ID>>();  in run()
856         let work_ptr = unsafe { Work::raw_get(work_ptr) };  in __enqueue()
861             // SAFETY: The work queue has not taken ownership of the pointer.  in __enqueue()
868 // `HasWork` provides a `work_struct` that is the `work` field of a `delayed_work`, and the rest of
869 // the `delayed_work` has the same access rules as its `work` field.
884         // The `__enqueue` method always uses a `work_struct` stored in a `Work<T, ID>`.  in run()
885         let ptr = ptr.cast::<Work<T, ID>>();  in run()
917         let work_ptr = unsafe { Work::raw_get(work_ptr) };  in __enqueue()
928 // `HasWork` provides a `work_struct` that is the `work` field of a `delayed_work`, and the rest of
929 // the `delayed_work` has the same access rules as its `work` field.
937 /// Returns the system work queue (`system_wq`).
942 /// Callers shouldn't queue work items which can run for too long.
948 /// Returns the system high-priority work queue (`system_highpri_wq`).
950 /// It is similar to the one returned by [`system`] but for work items which require higher
957 /// Returns the system work queue for potentially long-running work items (`system_long_wq`).
959 /// It is similar to the one returned by [`system`] but may host long running work items. Queue
966 /// Returns the system unbound work queue (`system_unbound_wq`).
968 /// Workers are not bound to any specific CPU, not concurrency managed, and all queued work items
976 /// Returns the system freezable work queue (`system_freezable_wq`).
980 /// A freezable workqueue participates in the freeze phase of the system suspend operations. Work
981 /// items on the workqueue are drained and no new work item starts execution until thawed.
987 /// Returns the system power-efficient work queue (`system_power_efficient_wq`).
997 /// Returns the system freezable power-efficient work queue (`system_freezable_power_efficient_wq`).
1001 /// A freezable workqueue participates in the freeze phase of the system suspend operations. Work
1002 /// items on the workqueue are drained and no new work item starts execution until thawed.
1008 /// Returns the system bottom halves work queue (`system_bh_wq`).
1010 /// It is similar to the one returned by [`system`] but for work items which
1017 /// Returns the system bottom halves high-priority work queue (`system_bh_highpri_wq`).
1019 /// It is similar to the one returned by [`system_bh`] but for work items which