[v3,9/9] rust: workqueue: add examples
Commit Message
This adds two examples of how to use the workqueue. The first example
shows how to use it when you only have one `work_struct` field, and the
second example shows how to use it when you have multiple `work_struct`
fields.
Signed-off-by: Alice Ryhl <aliceryhl@google.com>
Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com>
Reviewed-by: Gary Guo <gary@garyguo.net>
Reviewed-by: Andreas Hindborg (Samsung) <nmi@metaspace.dk>
Reviewed-by: Benno Lossin <benno.lossin@proton.me>
---
v2 -> v3:
* Use LockClassKey in constructors in examples.
* Add Reviewed-by from Martin, Gary, Andreas, Benno.
rust/kernel/workqueue.rs | 104 +++++++++++++++++++++++++++++++++++++++
1 file changed, 104 insertions(+)
Comments
On Tue, Jul 11, 2023 at 09:33:03AM +0000, Alice Ryhl wrote:
> This adds two examples of how to use the workqueue. The first example
> shows how to use it when you only have one `work_struct` field, and the
> second example shows how to use it when you have multiple `work_struct`
> fields.
>
These examples are nice, but look like we need the following based on
the whole patchset to make them compile as doc/kunit tests[1]:
diff --git a/rust/kernel/workqueue.rs b/rust/kernel/workqueue.rs
index d99f55a021dd..1ccc511dbe87 100644
--- a/rust/kernel/workqueue.rs
+++ b/rust/kernel/workqueue.rs
@@ -34,6 +34,7 @@
//!
//! ```
//! use kernel::prelude::*;
+//! use kernel::impl_has_work;
//! use kernel::sync::Arc;
//! use kernel::workqueue::{self, Work, WorkItem};
//!
@@ -76,6 +77,7 @@
//!
//! ```
//! use kernel::prelude::*;
+//! use kernel::impl_has_work;
//! use kernel::sync::Arc;
//! use kernel::workqueue::{self, Work, WorkItem};
//!
@@ -380,6 +382,7 @@ pub unsafe fn raw_get(ptr: *const Self) -> *mut bindings::work_struct {
///
/// ```no_run
/// use kernel::prelude::*;
+/// use kernel::impl_has_work;
/// use kernel::workqueue::Work;
///
/// struct MyWorkItem {
@@ -456,6 +459,8 @@ unsafe fn work_container_of(ptr: *mut Work<T, ID>) -> *mut Self
///
/// ```
/// use kernel::sync::Arc;
+/// use kernel::impl_has_work;
+/// use kernel::workqueue::{self, Work, WorkItem};
///
/// struct MyStruct {
/// work_field: Work<MyStruct, 17>,
[1]: https://lore.kernel.org/rust-for-linux/20230614180837.630180-1-ojeda@kernel.org/
Regards,
Boqun
> Signed-off-by: Alice Ryhl <aliceryhl@google.com>
> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com>
> Reviewed-by: Gary Guo <gary@garyguo.net>
> Reviewed-by: Andreas Hindborg (Samsung) <nmi@metaspace.dk>
> Reviewed-by: Benno Lossin <benno.lossin@proton.me>
> ---
> v2 -> v3:
> * Use LockClassKey in constructors in examples.
> * Add Reviewed-by from Martin, Gary, Andreas, Benno.
>
> rust/kernel/workqueue.rs | 104 +++++++++++++++++++++++++++++++++++++++
> 1 file changed, 104 insertions(+)
>
> diff --git a/rust/kernel/workqueue.rs b/rust/kernel/workqueue.rs
> index 3a3a8b52bfd9..482d3eeae7d8 100644
> --- a/rust/kernel/workqueue.rs
> +++ b/rust/kernel/workqueue.rs
> @@ -26,6 +26,110 @@
> //! * The `WorkItemPointer` trait is implemented for the pointer type that points at a something
> //! that implements `WorkItem`.
> //!
> +//! ## Example
> +//!
> +//! This example defines a struct that holds an integer and can be scheduled on the workqueue. When
> +//! the struct is executed, it will print the integer. Since there is only one `work_struct` field,
> +//! we do not need to specify ids for the fields.
> +//!
> +//! ```
> +//! use kernel::prelude::*;
> +//! use kernel::sync::Arc;
> +//! use kernel::workqueue::{self, Work, WorkItem};
> +//!
> +//! #[pin_data]
> +//! struct MyStruct {
> +//! value: i32,
> +//! #[pin]
> +//! work: Work<MyStruct>,
> +//! }
> +//!
> +//! impl_has_work! {
> +//! impl HasWork<Self> for MyStruct { self.work }
> +//! }
> +//!
> +//! impl MyStruct {
> +//! fn new(value: i32) -> Result<Arc<Self>> {
> +//! Arc::pin_init(pin_init!(MyStruct {
> +//! value,
> +//! work <- Work::new(kernel::static_lock_class!()),
> +//! }))
> +//! }
> +//! }
> +//!
> +//! impl WorkItem for MyStruct {
> +//! type Pointer = Arc<MyStruct>;
> +//!
> +//! fn run(this: Arc<MyStruct>) {
> +//! pr_info!("The value is: {}", this.value);
> +//! }
> +//! }
> +//!
> +//! /// This method will enqueue the struct for execution on the system workqueue, where its value
> +//! /// will be printed.
> +//! fn print_later(val: Arc<MyStruct>) {
> +//! let _ = workqueue::system().enqueue(val);
> +//! }
> +//! ```
> +//!
> +//! The following example shows how multiple `work_struct` fields can be used:
> +//!
> +//! ```
> +//! use kernel::prelude::*;
> +//! use kernel::sync::Arc;
> +//! use kernel::workqueue::{self, Work, WorkItem};
> +//!
> +//! #[pin_data]
> +//! struct MyStruct {
> +//! value_1: i32,
> +//! value_2: i32,
> +//! #[pin]
> +//! work_1: Work<MyStruct, 1>,
> +//! #[pin]
> +//! work_2: Work<MyStruct, 2>,
> +//! }
> +//!
> +//! impl_has_work! {
> +//! impl HasWork<Self, 1> for MyStruct { self.work_1 }
> +//! impl HasWork<Self, 2> for MyStruct { self.work_2 }
> +//! }
> +//!
> +//! impl MyStruct {
> +//! fn new(value_1: i32, value_2: i32) -> Result<Arc<Self>> {
> +//! Arc::pin_init(pin_init!(MyStruct {
> +//! value_1,
> +//! value_2,
> +//! work_1 <- Work::new(kernel::static_lock_class!()),
> +//! work_2 <- Work::new(kernel::static_lock_class!()),
> +//! }))
> +//! }
> +//! }
> +//!
> +//! impl WorkItem<1> for MyStruct {
> +//! type Pointer = Arc<MyStruct>;
> +//!
> +//! fn run(this: Arc<MyStruct>) {
> +//! pr_info!("The value is: {}", this.value_1);
> +//! }
> +//! }
> +//!
> +//! impl WorkItem<2> for MyStruct {
> +//! type Pointer = Arc<MyStruct>;
> +//!
> +//! fn run(this: Arc<MyStruct>) {
> +//! pr_info!("The second value is: {}", this.value_2);
> +//! }
> +//! }
> +//!
> +//! fn print_1_later(val: Arc<MyStruct>) {
> +//! let _ = workqueue::system().enqueue::<Arc<MyStruct>, 1>(val);
> +//! }
> +//!
> +//! fn print_2_later(val: Arc<MyStruct>) {
> +//! let _ = workqueue::system().enqueue::<Arc<MyStruct>, 2>(val);
> +//! }
> +//! ```
> +//!
> //! C header: [`include/linux/workqueue.h`](../../../../include/linux/workqueue.h)
>
> use crate::{bindings, prelude::*, sync::Arc, sync::LockClassKey, types::Opaque};
> --
> 2.41.0.255.g8b1d071c50-goog
>
@@ -26,6 +26,110 @@
//! * The `WorkItemPointer` trait is implemented for the pointer type that points at a something
//! that implements `WorkItem`.
//!
+//! ## Example
+//!
+//! This example defines a struct that holds an integer and can be scheduled on the workqueue. When
+//! the struct is executed, it will print the integer. Since there is only one `work_struct` field,
+//! we do not need to specify ids for the fields.
+//!
+//! ```
+//! use kernel::prelude::*;
+//! use kernel::sync::Arc;
+//! use kernel::workqueue::{self, Work, WorkItem};
+//!
+//! #[pin_data]
+//! struct MyStruct {
+//! value: i32,
+//! #[pin]
+//! work: Work<MyStruct>,
+//! }
+//!
+//! impl_has_work! {
+//! impl HasWork<Self> for MyStruct { self.work }
+//! }
+//!
+//! impl MyStruct {
+//! fn new(value: i32) -> Result<Arc<Self>> {
+//! Arc::pin_init(pin_init!(MyStruct {
+//! value,
+//! work <- Work::new(kernel::static_lock_class!()),
+//! }))
+//! }
+//! }
+//!
+//! impl WorkItem for MyStruct {
+//! type Pointer = Arc<MyStruct>;
+//!
+//! fn run(this: Arc<MyStruct>) {
+//! pr_info!("The value is: {}", this.value);
+//! }
+//! }
+//!
+//! /// This method will enqueue the struct for execution on the system workqueue, where its value
+//! /// will be printed.
+//! fn print_later(val: Arc<MyStruct>) {
+//! let _ = workqueue::system().enqueue(val);
+//! }
+//! ```
+//!
+//! The following example shows how multiple `work_struct` fields can be used:
+//!
+//! ```
+//! use kernel::prelude::*;
+//! use kernel::sync::Arc;
+//! use kernel::workqueue::{self, Work, WorkItem};
+//!
+//! #[pin_data]
+//! struct MyStruct {
+//! value_1: i32,
+//! value_2: i32,
+//! #[pin]
+//! work_1: Work<MyStruct, 1>,
+//! #[pin]
+//! work_2: Work<MyStruct, 2>,
+//! }
+//!
+//! impl_has_work! {
+//! impl HasWork<Self, 1> for MyStruct { self.work_1 }
+//! impl HasWork<Self, 2> for MyStruct { self.work_2 }
+//! }
+//!
+//! impl MyStruct {
+//! fn new(value_1: i32, value_2: i32) -> Result<Arc<Self>> {
+//! Arc::pin_init(pin_init!(MyStruct {
+//! value_1,
+//! value_2,
+//! work_1 <- Work::new(kernel::static_lock_class!()),
+//! work_2 <- Work::new(kernel::static_lock_class!()),
+//! }))
+//! }
+//! }
+//!
+//! impl WorkItem<1> for MyStruct {
+//! type Pointer = Arc<MyStruct>;
+//!
+//! fn run(this: Arc<MyStruct>) {
+//! pr_info!("The value is: {}", this.value_1);
+//! }
+//! }
+//!
+//! impl WorkItem<2> for MyStruct {
+//! type Pointer = Arc<MyStruct>;
+//!
+//! fn run(this: Arc<MyStruct>) {
+//! pr_info!("The second value is: {}", this.value_2);
+//! }
+//! }
+//!
+//! fn print_1_later(val: Arc<MyStruct>) {
+//! let _ = workqueue::system().enqueue::<Arc<MyStruct>, 1>(val);
+//! }
+//!
+//! fn print_2_later(val: Arc<MyStruct>) {
+//! let _ = workqueue::system().enqueue::<Arc<MyStruct>, 2>(val);
+//! }
+//! ```
+//!
//! C header: [`include/linux/workqueue.h`](../../../../include/linux/workqueue.h)
use crate::{bindings, prelude::*, sync::Arc, sync::LockClassKey, types::Opaque};