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>,
140 /// Creates a [`Work`] initialiser with the given name and a newly-created lock class.
144 …      $crate::workqueue::Work::new($crate::optional_name!($($name)?), $crate::static_lock_class!())
149 /// A kernel work queue.
153 /// It allows work items to be queued to run on thread pools managed by the kernel. Several are
176     /// Enqueues a work item.
178     /// This may fail if the work item is already enqueued in a workqueue.
180     /// The work item will be submitted using `WORK_CPU_UNBOUND`.
195         // `__enqueue`, then the work item was successfully enqueued, and `bindings::queue_work_on`  in enqueue()
209     /// Tries to spawn the given function or closure as a work item.
211     /// This method can fail because it allocates memory to store the work item.
218             work <- new_work!("Queue::try_spawn"),  in try_spawn()
233     work: Work<ClosureWork<T>>,  field
254 /// A raw work item.
278     /// Enqueues this work item on a queue using the provided `queue_work_on` method.
291     /// If the work item type is annotated with any lifetimes, then you must not call the function
294     /// If the work item type is not [`Send`], then the function pointer must be called on the same
301 /// Defines the method that should be called directly when a work item is executed.
309 /// This trait is used when the `work_struct` field is defined using the [`Work`] helper.
319     /// Run this work item.
330 /// Defines the method that should be called when this work item is executed.
332 /// This trait is used when the `work_struct` field is defined using the [`Work`] helper.
338     /// The method that should be called when this work item is executed.
342 /// Links for a work item.
345 /// trait, and defines the linked list pointers necessary to enqueue a work item in a workqueue.
354 pub struct Work<T: ?Sized, const ID: u64 = 0> {  struct
356     work: Opaque<bindings::work_struct>,  field
360 // SAFETY: Kernel work items are usable from any thread.
362 // We do not need to constrain `T` since the work item does not actually contain a `T`.
363 unsafe impl<T: ?Sized, const ID: u64> Send for Work<T, ID> {}  argument
364 // SAFETY: Kernel work items are usable from any thread.
366 // We do not need to constrain `T` since the work item does not actually contain a `T`.
367 unsafe impl<T: ?Sized, const ID: u64> Sync for Work<T, ID> {}  implementation
369 impl<T: ?Sized, const ID: u64> Work<T, ID> {  impl
370     /// Creates a new instance of [`Work`].
377             work <- Opaque::ffi_init(|slot| {  in new()
379                 // the work item function.  in new()
405         // the compiler does not complain that the `work` field is unused.  in raw_get()
406         unsafe { Opaque::raw_get(core::ptr::addr_of!((*ptr).work)) }  in raw_get()
410 /// Declares that a type has a [`Work<T, ID>`] field.
416 /// use kernel::workqueue::{impl_has_work, Work};
419 ///     work_field: Work<MyWorkItem, 1>,
427 /// Note that since the [`Work`] type is annotated with an id, you can have several `work_struct`
432 /// The [`OFFSET`] constant must be the offset of a field in `Self` of type [`Work<T, ID>`]. The
438     /// The offset of the [`Work<T, ID>`] field.
441     /// Returns the offset of the [`Work<T, ID>`] field.
452     /// Returns a pointer to the [`Work<T, ID>`] field.
458     unsafe fn raw_get_work(ptr: *mut Self) -> *mut Work<T, ID> {  in raw_get_work()
460         unsafe { (ptr as *mut u8).add(Self::OFFSET) as *mut Work<T, ID> }  in raw_get_work()
463     /// Returns a pointer to the struct containing the [`Work<T, ID>`] field.
467     /// The pointer must point at a [`Work<T, ID>`] field in a struct of type `Self`.
469     unsafe fn work_container_of(ptr: *mut Work<T, ID>) -> *mut Self  in work_container_of()
485 /// use kernel::workqueue::{self, impl_has_work, Work};
488 ///     work_field: Work<MyStruct<'a, T, N>, 17>,
510 …     unsafe fn raw_get_work(ptr: *mut Self) -> *mut $crate::workqueue::Work<$work_type $(, $id)?> {
522     impl{T} HasWork<Self> for ClosureWork<T> { self.work }
527 //   - `__enqueue` gets the `work_struct` from the `Work` field, using `T::raw_get_work`.
528 //   - The only safe way to create a `Work` object is through `Work::new`.
529 //   - `Work::new` makes sure that `T::Pointer::run` is passed to `init_work_with_key`.
530 //   - Finally `Work` and `RawWorkItem` guarantee that the correct `Work` field
532 //     uses the correct offset for the `Work` field, and `Work::new` picks the correct
540         // The `__enqueue` method always uses a `work_struct` stored in a `Work<T, ID>`.  in run()
541         let ptr = ptr as *mut Work<T, ID>;  in run()
575         let work_ptr = unsafe { Work::raw_get(work_ptr) };  in __enqueue()
580             // SAFETY: The work queue has not taken ownership of the pointer.  in __enqueue()
593         // The `__enqueue` method always uses a `work_struct` stored in a `Work<T, ID>`.  in run()
594         let ptr = ptr as *mut Work<T, ID>;  in run()
626         let work_ptr = unsafe { Work::raw_get(work_ptr) };  in __enqueue()
636 /// Returns the system work queue (`system_wq`).
641 /// Callers shouldn't queue work items which can run for too long.
647 /// Returns the system high-priority work queue (`system_highpri_wq`).
649 /// It is similar to the one returned by [`system`] but for work items which require higher
656 /// Returns the system work queue for potentially long-running work items (`system_long_wq`).
658 /// It is similar to the one returned by [`system`] but may host long running work items. Queue
665 /// Returns the system unbound work queue (`system_unbound_wq`).
667 /// Workers are not bound to any specific CPU, not concurrency managed, and all queued work items
675 /// Returns the system freezable work queue (`system_freezable_wq`).
679 /// A freezable workqueue participates in the freeze phase of the system suspend operations. Work
680 /// items on the workqueue are drained and no new work item starts execution until thawed.
686 /// Returns the system power-efficient work queue (`system_power_efficient_wq`).
696 /// Returns the system freezable power-efficient work queue (`system_freezable_power_efficient_wq`).
700 /// A freezable workqueue participates in the freeze phase of the system suspend operations. Work
701 /// items on the workqueue are drained and no new work item starts execution until thawed.