Commit 19574604 authored by I Hsin Cheng's avatar I Hsin Cheng Committed by Miguel Ojeda
Browse files

rust: list: Add examples for linked list 

Add basic examples for the structure "List", which also serve as unit
tests for basic list methods. It includes the following manipulations:
* List creation
* List emptiness check
* List insertion through push_front(), push_back()
* List item removal through pop_front(), pop_back()
* Push one list to another through push_all_back()

The method "remove()" doesn't have an example here because insertion
with push_front() or push_back() will take the ownership of the item,
which means we can't keep any valid reference to the node we want to
remove, unless Cursor is used. The "remove" example through Cursor is
already demonstrated with commit 52ae96f5 ("rust: list: make the
cursor point between elements").

Link: https://github.com/Rust-for-Linux/linux/issues/1121


Signed-off-by: default avatarI Hsin Cheng <richard120310@gmail.com>
Reviewed-by: default avatarAlice Ryhl <aliceryhl@google.com>
Reviewed-by: default avatarBenno Lossin <lossin@kernel.org>
Link: https://lore.kernel.org/r/20250311133357.90322-1-richard120310@gmail.com


[ Removed prelude import and spurious newlines. Formatted comments
  with the usual style. Reworded slightly. - Miguel ]
Signed-off-by: default avatarMiguel Ojeda <ojeda@kernel.org>
parent 28669b2f

rust/kernel/list.rs

+108 −0
Original line number Diff line number Diff line
@@ -35,6 +35,114 @@ 
/// * All prev/next pointers in `ListLinks` fields of items in the list are valid and form a cycle.

/// * For every item in the list, the list owns the associated [`ListArc`] reference and has

///   exclusive access to the `ListLinks` field.

///

/// # Examples

///

/// ```

/// use kernel::list::*;

///

/// #[pin_data]

/// struct BasicItem {

///     value: i32,

///     #[pin]

///     links: ListLinks,

/// }

///

/// impl BasicItem {

///     fn new(value: i32) -> Result<ListArc<Self>> {

///         ListArc::pin_init(try_pin_init!(Self {

///             value,

///             links <- ListLinks::new(),

///         }), GFP_KERNEL)

///     }

/// }

///

/// impl_has_list_links! {

///     impl HasListLinks<0> for BasicItem { self.links }

/// }

/// impl_list_arc_safe! {

///     impl ListArcSafe<0> for BasicItem { untracked; }

/// }

/// impl_list_item! {

///     impl ListItem<0> for BasicItem { using ListLinks; }

/// }

///

/// // Create a new empty list.

/// let mut list = List::new();

/// {

///     assert!(list.is_empty());

/// }

///

/// // Insert 3 elements using `push_back()`.

/// list.push_back(BasicItem::new(15)?);

/// list.push_back(BasicItem::new(10)?);

/// list.push_back(BasicItem::new(30)?);

///

/// // Iterate over the list to verify the nodes were inserted correctly.

/// // [15, 10, 30]

/// {

///     let mut iter = list.iter();

///     assert_eq!(iter.next().unwrap().value, 15);

///     assert_eq!(iter.next().unwrap().value, 10);

///     assert_eq!(iter.next().unwrap().value, 30);

///     assert!(iter.next().is_none());

///

///     // Verify the length of the list.

///     assert_eq!(list.iter().count(), 3);

/// }

///

/// // Pop the items from the list using `pop_back()` and verify the content.

/// {

///     assert_eq!(list.pop_back().unwrap().value, 30);

///     assert_eq!(list.pop_back().unwrap().value, 10);

///     assert_eq!(list.pop_back().unwrap().value, 15);

/// }

///

/// // Insert 3 elements using `push_front()`.

/// list.push_front(BasicItem::new(15)?);

/// list.push_front(BasicItem::new(10)?);

/// list.push_front(BasicItem::new(30)?);

///

/// // Iterate over the list to verify the nodes were inserted correctly.

/// // [30, 10, 15]

/// {

///     let mut iter = list.iter();

///     assert_eq!(iter.next().unwrap().value, 30);

///     assert_eq!(iter.next().unwrap().value, 10);

///     assert_eq!(iter.next().unwrap().value, 15);

///     assert!(iter.next().is_none());

///

///     // Verify the length of the list.

///     assert_eq!(list.iter().count(), 3);

/// }

///

/// // Pop the items from the list using `pop_front()` and verify the content.

/// {

///     assert_eq!(list.pop_front().unwrap().value, 30);

///     assert_eq!(list.pop_front().unwrap().value, 10);

/// }

///

/// // Push `list2` to `list` through `push_all_back()`.

/// // list: [15]

/// // list2: [25, 35]

/// {

///     let mut list2 = List::new();

///     list2.push_back(BasicItem::new(25)?);

///     list2.push_back(BasicItem::new(35)?);

///

///     list.push_all_back(&mut list2);

///

///     // list: [15, 25, 35]

///     // list2: []

///     let mut iter = list.iter();

///     assert_eq!(iter.next().unwrap().value, 15);

///     assert_eq!(iter.next().unwrap().value, 25);

///     assert_eq!(iter.next().unwrap().value, 35);

///     assert!(iter.next().is_none());

///     assert!(list2.is_empty());

/// }

/// # Result::<(), Error>::Ok(())

/// ```

pub struct List<T: ?Sized + ListItem<ID>, const ID: u64 = 0> {

    first: *mut ListLinksFields,

    _ty: PhantomData<ListArc<T, ID>>,