Skip to contentSkip to conversation

rust: types: Add examples for the `Either` type

PATCH Applied Nell Shamrell-Harrington 5 participants 6 messages Sep 18, 2024 – Oct 7, 2024 Rust

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 rust: types: Add examples for the `Either` type

Add examples for the Either type

---
V1 -> V2: Cleaned up commit message and addressed review comments

 rust/kernel/types.rs | 9 +++++++++
 1 file changed, 9 insertions(+)
rust/kernel/types.rs +9 -0
index 9e7ca066355c..e2f3ab11cfda 100644
@@ -461,6 +461,15 @@ fn drop(&mut self) {
 }
 
 /// A sum type that always holds either a value of type `L` or `R`.
+///
+/// # Examples
+///
+/// ```
+/// use kernel::types::Either;
+///
+/// let left_value: Either<i32, &str> = Either::Left(7);
+/// let right_value: Either<i32, &str> = Either::Right("right value");
+/// ```
 pub enum Either<L, R> {
     /// Constructs an instance of [`Either`] containing a value of type `L`.
     Left(L),
Signature · 1 line
2.34.1
Applied
#3 lore raw
In reply to Nell Shamrell-Harrington
Quoted 6 lines · Nell Shamrell-Harrington

Add examples for the Either type

Applied to rust-next -- thanks everyone!

[ Reworded slightly. - Miguel ]

It could be nice to have assert_eq!s too, like in some standard library examples and/or a "real-life" example like Wedson's (I created a "good first issue" for that:
https://github.com/Rust-for-Linux/linux/issues/1122), but we can add that later.

Cheers,
Miguel

#4 lore raw

PATCH 1/1 rust: types: 'real-life' example for Either

Added a 'real-life' example for the type Either. This example uses a work queue and extends the first example in workqueue.rs (commit ID: 15b286d) to demonstrate how to hold and distinguish between two different data types.

---
 rust/kernel/types.rs | 54 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
rust/kernel/types.rs +54 -0
index 5ea9126c8c93..a56192141a0c 100644
@@ -322,6 +322,60 @@ pub const fn raw_get(this: *const Self) -> *mut T {
 /// let left_value: Either<i32, &str> = Either::Left(7);
 /// let right_value: Either<i32, &str> = Either::Right("right value");
 /// ```
+///
+/// The following example demonstrates how we can create a struct
+/// that uses `Either` to hold either an integer or a string.
+/// This struct will be scheduled on the workqueue, and when executed,
+/// we will perform different actions depending on whether it holds
+/// a `Left` value (integer) or a `Right` value (string).
+///
+/// ```
+/// use kernel::prelude::*;
+/// use kernel::sync::Arc;
+/// use kernel::types::Either;
+/// use kernel::workqueue::{self, new_work, Work, WorkItem};
+///
+/// #[pin_data]
+/// struct WorkStruct {
+///     value: Either<i32, &'static str>,
+///     #[pin]
+///     work: Work<WorkStruct>,
+/// }
+///
+/// impl_has_work! {
+///     impl HasWork<Self> for WorkStruct { self.work }
+/// }
+///
+/// impl WorkStruct {
+///     fn new(value: Either<i32, &'static str>) -> Result<Arc<Self>> {
+///         Arc::pin_init(pin_init!(WorkStruct {
+///             value,
+///             work <- new_work!("WorkStruct::work"),
+///         }), GFP_KERNEL)
+///     }
+/// }
+///
+/// impl WorkItem for WorkStruct {
+///     type Pointer = Arc<WorkStruct>;
+///
+///     fn run(this: Arc<WorkStruct>) {
+///         match &this.value {
+///             Either::Left(left_value) => {
+///                 pr_info!("Left value: {}", left_value);
+///                 pr_info!("Left value times two: {}", left_value << 1);
+///             }
+///             Either::Right(right_value) => {
+///                 pr_info!("Right value: {}", right_value);
+///                 pr_info!("Length of right value: {}", right_value.len());
+///             }
+///         }
+///     }
+/// }
+///
+/// fn enqueue_work(work_item: Arc<WorkStruct>) {
+///     let _ = workqueue::system().enqueue(work_item);
+/// }
+/// ```
 pub enum Either<L, R> {
     /// Constructs an instance of [`Either`] containing a value of type `L`.
     Left(L),

--
2.46.2

#5 lore raw

Re: [PATCH] rust: types: 'real-life' example for Either

Quoted 9 lines · Timo Grautstueck

Added a 'real-life' example for the type Either. This example uses a work queue and extends the first example in workqueue.rs (commit ID: 15b286d) to demonstrate how to hold and distinguish between two different data types.

This is a nice, self-contained example, thanks!

In the linked issue, I was aiming more to have a case where Either was used in an interface (or similar) carrying two existing different types, i.e. like in the talk I mentioned in the issue. I feel a custom enum may work better anyway for something like the example in this patch, i.e. when one does not have already types on each side that make it obvious what each side is about.

So perhaps we can modify this example with two "message" or "action" types (that may be hidden) or something similar that Either can carry, so that it is a bit more concrete.

It wouldn't hurt either to showcase in addition the interface the talk showed, perhaps in an ignore example so that we don't have to "mock" everything.

Cheers,
Miguel