Messages in this thread | | | Date | Tue, 6 Jun 2023 16:36:30 -0700 | From | Boqun Feng <> | Subject | Re: [PATCH v2 1/8] rust: workqueue: add low-level workqueue bindings |
| |
On Thu, Jun 01, 2023 at 01:49:39PM +0000, Alice Ryhl wrote: [...] > +/// A raw work item. > +/// > +/// This is the low-level trait that is designed for being as general as possible. > +/// > +/// The `ID` parameter to this trait exists so that a single type can provide multiple > +/// implementations of this trait. For example, if a struct has multiple `work_struct` fields, then > +/// you will implement this trait once for each field, using a different id for each field. The > +/// actual value of the id is not important as long as you use different ids for different fields > +/// of the same struct. (Fields of different structs need not use different ids.) > +/// > +/// Note that the id is used only to select the right method to call during compilation. It wont be > +/// part of the final executable. > +/// > +/// # Safety > +/// > +/// Implementers must ensure that any pointers passed to a `queue_work_on` closure by `__enqueue` > +/// remain valid for the duration specified in the documentation for `__enqueue`.
^ better to say "the #Guarantees section in the documentation for `__enqueue`"?
Regards, Boqun
> +pub unsafe trait RawWorkItem<const ID: u64> { > + /// The return type of [`Queue::enqueue`]. > + type EnqueueOutput; > + > + /// Enqueues this work item on a queue using the provided `queue_work_on` method. > + /// > + /// # Guarantees > + /// > + /// If this method calls the provided closure, then the raw pointer is guaranteed to point at a > + /// valid `work_struct` for the duration of the call to the closure. If the closure returns > + /// true, then it is further guaranteed that the pointer remains valid until someone calls the > + /// function pointer stored in the `work_struct`. > + /// > + /// # Safety > + /// > + /// The provided closure may only return `false` if the `work_struct` is already in a workqueue. > + /// > + /// If the work item type is annotated with any lifetimes, then you must not call the function > + /// pointer after any such lifetime expires. (Never calling the function pointer is okay.) > + /// > + /// If the work item type is not [`Send`], then the function pointer must be called on the same > + /// thread as the call to `__enqueue`. > + unsafe fn __enqueue<F>(self, queue_work_on: F) -> Self::EnqueueOutput > + where > + F: FnOnce(*mut bindings::work_struct) -> bool; > +} > -- > 2.41.0.rc0.172.g3f132b7071-goog >
| |