Cordyceps

https://docs.rs/cordyceps/latest/
Admin
Cordyceps is a Rust library providing intrusive data structures including doubly-linked lists,...
Tokens:135,495
Snippets:1,282
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### MpscQueue Example with Custom Entry Type

Source: https://docs.rs/cordyceps/latest/src/cordyceps/mpsc_queue.rs.html

Demonstrates how to define a custom entry type and implement the `Linked` trait for use with `MpscQueue`. This setup is necessary before constructing and using the queue.

```rust
use cordyceps::
    Linked,
    mpsc_queue::{self, MpscQueue},
};

// This example uses the Rust standard library for convenience, but
// the MPSC queue itself does not require std.
use std::{pin::Pin, ptr::{self, NonNull}, thread, sync::Arc};

/// A simple queue entry that stores an `i32`.
#[derive(Debug, Default)]
struct Entry {
   links: mpsc_queue::Links<Entry>,
   val: i32,
}

// Implement the `Linked` trait for our entry type so that it can be used
// as a queue entry.
unsafe impl Linked<mpsc_queue::Links<Entry>> for Entry {
    // In this example, our entries will be "owned" by a `Box`, but any
    // heap-allocated type that owns an element may be used.
    //
    // An element *must not* move while part of an intrusive data
    // structure. In many cases, `Pin` may be used to enforce this.
    type Handle = Pin<Box<Self>>;

    /// Convert an owned `Handle` into a raw pointer
    fn into_ptr(handle: Pin<Box<Entry>>) -> NonNull<Entry> {
       unsafe { NonNull::from(Box::leak(Pin::into_inner_unchecked(handle))) }
    }

    /// Convert a raw pointer back into an owned `Handle`.
    unsafe fn from_ptr(ptr: NonNull<Entry>) -> Pin<Box<Entry>> {
        // Safety: if this function is only called by the linked list
        // implementation (and it is not intended for external use), we can
        // expect that the `NonNull` was constructed from a reference which
        // was pinned.
        //
        // If other callers besides `MpscQueue`'s internals were to call this on
        // some random `NonNull<Entry>`, this would not be the case, and
        // this could be constructing an erroneous `Pin` from a referent
        // that may not be pinned!
        Pin::new_unchecked(Box::from_raw(ptr.as_ptr()))
    }

    /// Access an element's `Links`.
    unsafe fn links(target: NonNull<Entry>) -> NonNull<mpsc_queue::Links<Entry>> {
        // Using `ptr::addr_of_mut!` permits us to avoid creating a temporary
        // reference without using layout-dependent casts.
        let links = ptr::addr_of_mut!((*target.as_ptr()).links);

        // `NonNull::new_unchecked` is safe to use here, because the pointer that
        // we offset was not null, implying that the pointer produced by offsetting
        // it will also not be null.
        NonNull::new_unchecked(links)
    }
}

impl Entry {
    fn new(val: i32) -> Self {
        Self {
            val,
            ..Self::default()
        }
    }
}

// Once we have a `Linked` implementation for our element type, we can construct
// a queue.

// Because `Pin<Box<...>>` doesn't have a `Default` impl, we have to manually
// construct the stub node.
let stub = Box::pin(Entry::default());
let q = Arc::new(MpscQueue::<Entry>::new_with_stub(stub));

// Spawn some producer threads.
thread::spawn({
    let q = q.clone();
    move || {
        // Enqueuing elements does not require waiting, and is not fallible.
        q.enqueue(Box::pin(Entry::new(1)));
        q.enqueue(Box::pin(Entry::new(2)));
    }
});

thread::spawn({
    let q = q.clone();
    move || {

```

--------------------------------

### MPSC Queue Producer and Consumer Example (Larger)

Source: https://docs.rs/cordyceps/latest/src/cordyceps/mpsc_queue.rs.html

Demonstrates enqueuing a larger batch of elements and consuming them. This example is similar to the previous one but uses a different range for enqueuing, testing the queue's capacity and handling of more items.

```rust
let q = Arc::new(MpscQueue::new());
let producer = {
    let q = Arc::clone(&q);
    thread::spawn(move || {
        for i in 5..=10 {
            q.enqueue(Box::pin(Entry::new(i)));
        }
    })
};

let mut seen = Vec::new();
loop {
    // Make sure we run at least once, in case the producer is already done.
    let done = Arc::strong_count(&q) == 1;

    // Append any elements currently in the queue to the `Vec`
    seen.extend(q.consume().map(|entry| entry.as_ref().val));

    if done {
        break;
    }

    thread::yield_now();
}

producer.join().unwrap();

&mut seen[..].sort();
assert_eq!(&[5, 6, 7, 8, 9, 10], &seen[..]);
```

--------------------------------

### step_by

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.Cursor.html

Creates an iterator starting at the same point, but stepping by the given amount at each iteration.

```APIDOC
## step_by

### Description
Creates an iterator starting at the same point, but stepping by the given amount at each iteration.

### Signature
`fn step_by(self, step: usize) -> StepBy<Self>`

### Constraints
`where Self: Sized`
```

--------------------------------

### Linked Trait Implementation Example

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.List.html

Example demonstrating how to implement the `Linked` trait for a custom entry type to be used with `cordyceps::list::List`.

```APIDOC
## §Examples

### Implementing the `Linked` trait for an entry type:
```rust
use cordyceps::{
    Linked,
    list::{self, List},
};

// This example uses the Rust standard library for convenience, but
// the doubly-linked list itself does not require std.
use std::{pin::Pin, ptr::{self, NonNull}, thread, sync::Arc};

/// A simple queue entry that stores an `i32`.
#[derive(Debug, Default)]
struct Entry {
   links: list::Links<Entry>,
   val: i32,
}

// Implement the `Linked` trait for our entry type so that it can be used
// as a queue entry.
unsafe impl Linked<list::Links<Entry>> for Entry {
    // In this example, our entries will be "owned" by a `Box`, but any
    // heap-allocated type that owns an element may be used.
    //
    // An element *must not* move while part of an intrusive data
    // structure. In many cases, `Pin` may be used to enforce this.
    type Handle = Pin<Box<Self>>;

    /// Convert an owned `Handle` into a raw pointer
    fn into_ptr(handle: Pin<Box<Entry>>) -> NonNull<Entry> {
       unsafe { NonNull::from(Box::leak(Pin::into_inner_unchecked(handle))) }
    }

    /// Convert a raw pointer back into an owned `Handle`.
    unsafe fn from_ptr(ptr: NonNull<Entry>) -> Pin<Box<Entry>> {
        // Safety: if this function is only called by the linked list
        // implementation (and it is not intended for external use), we can
        // expect that the `NonNull` was constructed from a reference which
        // was pinned.
        //
        // If other callers besides `List`'s internals were to call this on
        // some random `NonNull<Entry>`, this would not be the case, and
        // this could be constructing an erroneous `Pin` from a referent
        // that may not be pinned!
        Pin::new_unchecked(Box::from_raw(ptr.as_ptr()))
    }

    /// Access an element's `Links`.
    unsafe fn links(target: NonNull<Entry>) -> NonNull<list::Links<Entry>> {
        // Using `ptr::addr_of_mut!` permits us to avoid creating a temporary
        // reference without using layout-dependent casts.
        let links = ptr::addr_of_mut!((*target.as_ptr()).links);

        // `NonNull::new_unchecked` is safe to use here, because the pointer that
        // we offset was not null, implying that the pointer produced by offsetting
        // it will also not be null.
        NonNull::new_unchecked(links)
    }
}

impl Entry {
    fn new(val: i32) -> Self {
        Self {
            val,
            ..Self::default()
        }
    }
}
```
```

--------------------------------

### MPSC Queue Producer and Consumer Example

Source: https://docs.rs/cordyceps/latest/src/cordyceps/mpsc_queue.rs.html

Demonstrates spawning multiple producer threads to enqueue messages and a single consumer thread to dequeue them. Handles potential dequeue errors.

```rust
            .map(|thread| {
                let q = q.clone();
                thread::spawn(move || {
                    for i in 0..MSGS {
                        q.enqueue(entry(i));
                        println!("thread {thread}; msg {i}/{MSGS}");
                    }
                })
            })
            .collect();

        let mut i = 0;
        while i < THREADS * MSGS {
            match q.try_dequeue() {
                Ok(msg) => {
                    i += 1;
                    println!("recv {msg:?} ({i}/{})", THREADS * MSGS);
                }
                Err(TryDequeueError::Busy) => {
                    panic!("the queue should never be busy, as there is only one consumer")
                }
                Err(e) => {
                    println!("recv error {e:?}");
                    thread::yield_now();
                }
            }
        }

        for thread in threads {
            thread.join().unwrap();
        }
```

--------------------------------

### Model function for Test Setup

Source: https://docs.rs/cordyceps/latest/src/cordyceps/loom.rs.html

Sets up the tracing subscriber for tests and uses the Builder to check a given closure. This is useful for creating isolated test environments for allocation tracking.

```rust
pub(crate) fn model(f: impl FnOnce()) {
        let collector = tracing_subscriber::fmt()
            .with_max_level(tracing::Level::TRACE)
            .with_test_writer()
            .without_time()
            .with_thread_ids(true)
            .with_thread_names(false)
            .finish();
        let _ = tracing::subscriber::set_global_default(collector);
        model::Builder::new().check(f)
    }
```

--------------------------------

### MpscQueue Producer and Consumer Example

Source: https://docs.rs/cordyceps/latest/cordyceps/mpsc_queue/struct.MpscQueue.html

Demonstrates how to use an MpscQueue for inter-thread communication. The producer enqueues items, and the consumer dequeues them, processing until the producer is finished.

```rust
let q = q.clone();
move || {
    for i in 5..=10 {
        q.enqueue(Box::pin(Entry::new(i)));
    }
}
});

let mut seen = Vec::new();
loop {
    // Make sure we run at least once, in case the producer is already done.
    let done = Arc::strong_count(&q) == 1;

    // Append any elements currently in the queue to the `Vec`
    seen.extend(q.consume().map(|entry| entry.as_ref().val));

    if done {
        break;
    }

    thread::yield_now();
}

&mut seen[..].sort();
assert_eq!(&[1, 2, 3, 4, 5, 6, 7, 8, 9, 10], &seen[..]);
```

--------------------------------

### Starting Allocation Tracking

Source: https://docs.rs/cordyceps/latest/src/cordyceps/loom.rs.html

Initiates tracking for a specific type `T` within the current allocation registry. This function is marked with `#[track_caller]` to capture the exact location of the allocation start.

```rust
#[track_caller]
                pub(super) fn start_tracking<T>() -> Option<Arc<TrackData>> {
                    // we don't use `Option::map` here because it creates a
                    // closure, which breaks `#[track_caller]`, since the caller
                    // of `insert` becomes the closure, which cannot have a
                    // `#[track_caller]` attribute on it.
                    #[allow(clippy::manual_map)]
                    match Self::current() {
                        Some(registry) => Some(registry.insert::<T>()),
                        _ => None,
                    }
                }
```

--------------------------------

### Cursor Methods

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.Cursor.html

Provides methods for interacting with the Cursor, such as getting its index, moving its position, and peeking at elements.

```APIDOC
## Cursor Methods

### `index()`

Returns the index of this cursor’s position in the `List`.
This returns `None` if the cursor is currently pointing to the null element.

### `move_next()`

Moves the cursor position to the next element in the `List`.
If the cursor is pointing at the null element, this moves it to the first element in the `List`. If it is pointing to the last element in the list, then this will move it to the null element.

### `move_prev()`

Moves the cursor to the previous element in the `List`.
If the cursor is pointing at the null element, this moves it to the last element in the `List`. If it is pointing to the first element in the list, then this will move it to the null element.

### `current()`

Borrows the element that the cursor is currently pointing at.
This returns `None` if the cursor is currently pointing to the null element.

### `peek_next()`

Borrows the next element after the cursor’s current position in the list.
If the cursor is pointing to the null element, this returns the first element in the `List`. If the cursor is pointing to the last element in the `List`, this returns `None`.

### `peek_prev()`

Borrows the previous element before the cursor’s current position in the list.
If the cursor is pointing to the null element, this returns the last element in the `List`. If the cursor is pointing to the first element in the `List`, this returns `None`.

### `len()`

Returns the length of the `List` this cursor points to.

### `is_empty()`

Returns `true` if the `List` this cursor points to is empty
```

--------------------------------

### MPSC Queue Producer and Consumer Example

Source: https://docs.rs/cordyceps/latest/src/cordyceps/mpsc_queue.rs.html

Demonstrates enqueuing elements from one thread and consuming them in another. The consumer loop ensures all elements are processed, even if the producer finishes early. It checks for producer completion by comparing strong reference counts.

```rust
let q = Arc::new(MpscQueue::new());
let producer = {
    let q = Arc::clone(&q);
    thread::spawn(move || {
        for i in 1..=4 {
            q.enqueue(Box::pin(Entry::new(i)));
        }
    })
};

let mut seen = Vec::new();
loop {
    // Make sure we run at least once, in case the producer is already done.
    let done = Arc::strong_count(&q) == 1;

    // Append any elements currently in the queue to the `Vec`
    seen.extend(q.consume().map(|entry| entry.as_ref().val));

    if done {
        break;
    }

    thread::yield_now();
}

producer.join().unwrap();

&mut seen[..].sort();
assert_eq!(&[1, 2, 3, 4], &seen[..]);
```

--------------------------------

### CursorMut Constructor

Source: https://docs.rs/cordyceps/latest/src/cordyceps/list/cursor.rs.html

Provides a constructor for creating a new mutable cursor. It initializes the cursor's core with the list, the starting link, and the index.

```rust
impl<'list, T: Linked<Links<T>> + ?Sized> CursorMut<'list, T> {
    pub(super) fn new(list: &'list mut List<T>, curr: Link<T>, index: usize) -> Self {
        Self {
            core: CursorCore { list, index, curr },
        }
    }

    /// Returns the index of this cursor's position in the [`List`].
    ///
    /// This returns `None` if the cursor is currently pointing to the
    /// null element.
    pub fn index(&self) -> Option<usize> {
        self.core.index()
    }

    /// Moves the cursor position to the next element in the [`List`].
    ///
    /// If the cursor is pointing at the null element, this moves it to the first
    /// element in the [`List`]. If it is pointing to the last element in the
    /// list, then this will move it to the null element.
    pub fn move_next(&mut self) {
        self.core.move_next()
    }
}
```

--------------------------------

### CursorCore::index - Get index from core

Source: https://docs.rs/cordyceps/latest/src/cordyceps/list/cursor.rs.html

Internal method to get the current index, returning None if the current link is null.

```rust
fn index(&self) -> Option<usize> {
        self.curr?;
        Some(self.index)
    }
```

--------------------------------

### Using List as a FIFO Queue

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.List.html

Demonstrates how to use the `List` as a First-In, First-Out (FIFO) queue using `push_back` and `pop_front`.

```APIDOC
## Using a `List` as a first-in, first-out (FIFO) queue with `List::push_back` and `List::pop_front`:
```rust
// Now that we've implemented the `Linked` trait for our `Entry` type, we can
// create a `List` of entries:
let mut list = List::<Entry>::new();

// Push some entries to the list:
for i in 0..5 {
    list.push_back(Box::pin(Entry::new(i)));
}

// The list is a doubly-ended queue. We can use the `pop_front` method with
// `push_back` to dequeue elements in FIFO order:
for i in 0..5 {
    let entry = list.pop_front()
        .expect("the list should have 5 entries in it");
    assert_eq!(entry.val, i, "entries are dequeued in FIFO order");
}

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

--------------------------------

### Helper to get Links from a Node

Source: https://docs.rs/cordyceps/latest/src/cordyceps/mpsc_queue.rs.html

An inline helper function to safely get a reference to the `Links` of a node, avoiding repeated `.as_ref()` calls.

```rust
/// Just a little helper so we don't have to add `.as_ref()` noise everywhere...
#[inline(always)]
unsafe fn links<'a, T: Linked<Links<T>>>(ptr: NonNull<T>) -> &'a Links<T> {
    T::links(ptr).as_ref()
}
```

--------------------------------

### Using List as a LIFO Stack

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.List.html

Demonstrates how to use the `List` as a Last-In, First-Out (LIFO) stack using `push_back` and `pop_back`.

```APIDOC
## Using a `List` as a last-in, first-out (LIFO) stack with `List::push_back` and `List::pop_back`:
```rust
let mut list = List::<Entry>::new();

// Push some entries to the list:
for i in 0..5 {
    list.push_back(Box::pin(Entry::new(i)));
}

// Note that we have reversed the direction of the iterator, since
// we are popping from the *back* of the list:
for i in (0..5).into_iter().rev() {
    let entry = list.pop_back()
        .expect("the list should have 5 entries in it");
    assert_eq!(entry.val, i, "entries are dequeued in LIFO order");
}

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

--------------------------------

### type_id

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.Iter.html

Gets the `TypeId` of `self`.

```APIDOC
#### fn type_id(&self) -> TypeId
Gets the `TypeId` of `self`. Read more
```

--------------------------------

### List::new

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.List.html

Creates and returns a new, empty `List`.

```APIDOC
### impl<T: Linked<Links<T>> + ?Sized> List<T>

#### pub const fn new() -> List<T>

Returns a new empty list.
```

--------------------------------

### type_id

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.IterMut.html

Gets the `TypeId` of `self`.

```APIDOC
## fn type_id(&self) -> TypeId
Gets the `TypeId` of `self`. Read more
```

--------------------------------

### Create a new Entry

Source: https://docs.rs/cordyceps/latest/src/cordyceps/stack.rs.html

Constructs a new `Entry` with a given value and initializes its links and tracking.

```rust
pub(crate) fn new(val: i32) -> Pin<Box<Entry>> {
            Box::pin(Entry {
                links: Links::new(),
                val,
                track: alloc::Track::new(()),
            })
        }
```

--------------------------------

### Basic MpscQueue Usage with Custom Entry

Source: https://docs.rs/cordyceps/latest/cordyceps/struct.MpscQueue.html

Demonstrates creating an MpscQueue with a custom `Entry` type, enqueuing elements from multiple threads, and dequeuing them. Requires implementing the `Linked` trait for the entry type.

```rust
use cordyceps::
    Linked,
    mpsc_queue::{self, MpscQueue},
};

// This example uses the Rust standard library for convenience, but
// the MPSC queue itself does not require std.
use std::{pin::Pin, ptr::{self, NonNull}, thread, sync::Arc};

/// A simple queue entry that stores an `i32`.
#[derive(Debug, Default)]
struct Entry {
   links: mpsc_queue::Links<Entry>,
   val: i32,
}

// Implement the `Linked` trait for our entry type so that it can be used
// as a queue entry.
unsafe impl Linked<mpsc_queue::Links<Entry>> for Entry {
    // In this example, our entries will be "owned" by a `Box`, but any
    // heap-allocated type that owns an element may be used.
    //
    // An element *must not* move while part of an intrusive data
    // structure. In many cases, `Pin` may be used to enforce this.
    type Handle = Pin<Box<Self>>;

    /// Convert an owned `Handle` into a raw pointer
    fn into_ptr(handle: Pin<Box<Entry>>) -> NonNull<Entry> {
       unsafe { NonNull::from(Box::leak(Pin::into_inner_unchecked(handle))) }
    }

    /// Convert a raw pointer back into an owned `Handle`.
    unsafe fn from_ptr(ptr: NonNull<Entry>) -> Pin<Box<Entry>> {
        // Safety: if this function is only called by the linked list
        // implementation (and it is not intended for external use), we can
        // expect that the `NonNull` was constructed from a reference which
        // was pinned.
        //
        // If other callers besides `MpscQueue`'s internals were to call this on
        // some random `NonNull<Entry>`, this would not be the case, and
        // this could be constructing an erroneous `Pin` from a referent
        // that may not be pinned!
        Pin::new_unchecked(Box::from_raw(ptr.as_ptr()))
    }

    /// Access an element's `Links`.
    unsafe fn links(target: NonNull<Entry>) -> NonNull<mpsc_queue::Links<Entry>> {
        // Using `ptr::addr_of_mut!` permits us to avoid creating a temporary
        // reference without using layout-dependent casts.
        let links = ptr::addr_of_mut!((*target.as_ptr()).links);

        // `NonNull::new_unchecked` is safe to use here, because the pointer that
        // we offset was not null, implying that the pointer produced by offsetting
        // it will also not be null.
        NonNull::new_unchecked(links)
    }
}

impl Entry {
    fn new(val: i32) -> Self {
        Self {
            val,
            ..Self::default()
        }
    }
}

// Once we have a `Linked` implementation for our element type, we can construct
// a queue.

// Because `Pin<Box<...>>` doesn't have a `Default` impl, we have to manually
// construct the stub node.
let stub = Box::pin(Entry::default());
let q = Arc::new(MpscQueue::<Entry>::new_with_stub(stub));

// Spawn some producer threads.
thread::spawn({
    let q = q.clone();
    move || {
        // Enqueuing elements does not require waiting, and is not fallible.
        q.enqueue(Box::pin(Entry::new(1)));
        q.enqueue(Box::pin(Entry::new(2)));
    }
});

thread::spawn({
    let q = q.clone();
    move || {
        q.enqueue(Box::pin(Entry::new(3)));
        q.enqueue(Box::pin(Entry::new(4)));
    }
});


// Dequeue elements until the producer threads have terminated.
let mut seen = Vec::new();
loop {
    // Make sure we run at least once, in case the producer is already done.
    let done = Arc::strong_count(&q) == 1;

    // Dequeue until the queue is empty.
    while let Some(entry) = q.dequeue() {
        seen.push(entry.as_ref().val);
    }

    // If there are still producers, we may continue dequeuing.
    if done {
        break;
    }

    thread::yield_now();
}

// The elements may not have been received in order, so sort the
// received values before making assertions about them.
&mut seen[..].sort();

assert_eq!(&[1, 2, 3, 4], &seen[..]);

```

--------------------------------

### Any Trait Implementation

Source: https://docs.rs/cordyceps/latest/cordyceps/struct.Stack.html

Provides the `type_id` method to get the unique TypeId of the stack.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Method
`type_id`

### Parameters
None

### Response
- **TypeId**: The unique identifier for the type of the stack.
```

--------------------------------

### Conversion Methods

Source: https://docs.rs/cordyceps/latest/cordyceps/stack/struct.TransferStack.html

Details the conversion capabilities using `From`, `Into`, `TryFrom`, and `TryInto` traits.

```APIDOC
## impl<T> From<T> for T

### Description
Provides a way to create a TransferStack from a value of the same type.

### Method
`from`

### Parameters
- `t` (T) - The value to convert.
```

```APIDOC
## impl<T, U> Into<U> for T

### Description
Provides a way to convert a TransferStack into another type `U` if `U` implements `From<T>`.

### Method
`into`

### Parameters
None

### Returns
- `U` - The converted value.
```

```APIDOC
## impl<T, U> TryFrom<U> for T

### Description
Provides a fallible way to convert a value of type `U` into a TransferStack of type `T`.

### Type Alias
- `Error`: `Infallible` - The type returned in the event of a conversion error.

### Method
`try_from`

### Parameters
- `value` (U) - The value to convert.

### Returns
- `Result<T, <T as TryFrom<U>>::Error>` - A result containing the converted value or an error.
```

```APIDOC
## impl<T, U> TryInto<U> for T

### Description
Provides a fallible way to convert a TransferStack into another type `U`.

### Type Alias
- `Error`: `<U as TryFrom<T>>::Error` - The type returned in the event of a conversion error.

### Method
`try_into`

### Parameters
None

### Returns
- `Result<U, <U as TryFrom<T>>::Error>` - A result containing the converted value or an error.
```

--------------------------------

### Get List Length

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.Cursor.html

Returns the total number of elements in the list that the cursor is associated with.

```rust
pub fn len(&self) -> usize
```

--------------------------------

### Create SortedList from Stack (smallest first)

Source: https://docs.rs/cordyceps/latest/cordyceps/sorted_list/struct.SortedList.html

Creates a new sorted list by consuming an existing stack, with the smallest items sorted first.

```rust
pub fn from_stack_min(stack: Stack<T>) -> Self
```

--------------------------------

### Iterators

Source: https://docs.rs/cordyceps/latest/src/cordyceps/list.rs.html

Provides methods to get iterators for traversing the list by reference, mutable reference, or pointer.

```APIDOC
## iter

### Description
Returns an iterator over the items in the list, providing immutable references to each element.

### Method Signature
`pub fn iter(&self) -> Iter<'_, T>`

## iter_mut

### Description
Returns an iterator over the items in the list, providing mutable references to each element.

### Method Signature
`pub fn iter_mut(&mut self) -> IterMut<'_, T>`

## iter_pointers

### Description
Returns an iterator over the items in the list, providing raw pointers (`NonNull<T>`) to each element. Use with caution.

### Safety
Care must be taken with the items yielded by this iterator, as they are raw pointers and do not carry Rust's usual safety guarantees.
```

--------------------------------

### try_from

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.IterMut.html

Performs the conversion.

```APIDOC
## fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
Performs the conversion.
```

--------------------------------

### Immutable Cursor at Back

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.List.html

Provides an immutable cursor starting at the last element, allowing iteration and seeking.

```APIDOC
## cursor_back

### Description
Returns a `Cursor` starting at the last element.
The `Cursor` type can be used as `Iterator` over this list. In addition, it may be seeked back and forth to an arbitrary position in the list.

### Method
`pub fn cursor_back(&self) -> Cursor<'_, T>`
```

--------------------------------

### Create MpscQueue with Static Stub

Source: https://docs.rs/cordyceps/latest/cordyceps/mpsc_queue/struct.MpscQueue.html

Demonstrates creating an MpscQueue in a static context using `new_with_static_stub`. The stub element is not dropped when the queue is dropped, requiring manual memory management if necessary. The stub must be unique to this queue instance.

```rust
#[derive(Debug, Default)]
struct Entry {
   links: mpsc_queue::Links<Entry>,
   val: i32,
}



static MPSC: MpscQueue<Entry> = {
    static STUB_ENTRY: Entry = Entry {
        links: mpsc_queue::Links::<Entry>::new_stub(),
        val: 0
    };

    // SAFETY: The stub may not be used by another MPSC queue.
    // Here, this is ensured because the `STUB_ENTRY` static is defined
    // inside of the initializer for the `MPSC` static, so it cannot be referenced
    // elsewhere.
    unsafe { MpscQueue::new_with_static_stub(&STUB_ENTRY) }
};
```

--------------------------------

### Recommended Linked::links implementation using addr_of_mut!

Source: https://docs.rs/cordyceps/latest/cordyceps/trait.Linked.html

The recommended and sound implementation of `Linked::links` using the `core::ptr::addr_of_mut!` macro to avoid temporary references.

```rust
use core::ptr::{self, NonNull};

unsafe impl Linked<list::Links<Self>> for Entry {
    // ...

    unsafe fn links(target: NonNull<Self>) -> NonNull<list::Links<Self>> {
        let target = target.as_ptr();

        // Using the `ptr::addr_of_mut!` macro, we can offset a raw pointer to a
        // raw pointer to a field *without* creating a temporary reference.
        let links = ptr::addr_of_mut!((*target).links);

        // `NonNull::new_unchecked` is safe to use here, because the pointer that
        // we offset was not null, implying that the pointer produced by offsetting
        // it will also not be null.
        NonNull::new_unchecked(links)
    }
}
```

--------------------------------

### Immutable Cursor at Front

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.List.html

Provides an immutable cursor starting at the first element, allowing iteration and seeking.

```APIDOC
## cursor_front

### Description
Returns a `Cursor` starting at the first element.
The `Cursor` type can be used as `Iterator` over this list. In addition, it may be seeked back and forth to an arbitrary position in the list.

### Method
`pub fn cursor_front(&self) -> Cursor<'_, T>`
```

--------------------------------

### Use `List` as a FIFO queue

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.List.html

Demonstrates using `List::push_back` and `List::pop_front` to implement a first-in, first-out queue. Elements are added to the back and removed from the front.

```rust
// Now that we've implemented the `Linked` trait for our `Entry` type, we can
// create a `List` of entries:
let mut list = List::<Entry>::new();

// Push some entries to the list:
for i in 0..5 {
    list.push_back(Box::pin(Entry::new(i)));
}

// The list is a doubly-ended queue. We can use the `pop_front` method with
// `push_back` to dequeue elements in FIFO order:
for i in 0..5 {
    let entry = list.pop_front()
        .expect("the list should have 5 entries in it");
    assert_eq!(entry.val, i, "entries are dequeued in FIFO order");
}

assert!(list.is_empty());

```

--------------------------------

### Mutable Cursor at Back

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.List.html

Provides a mutable cursor starting at the last element, allowing iteration and structural modification.

```APIDOC
## cursor_back_mut

### Description
Returns a `CursorMut` starting at the last element.
The `CursorMut` type can be used as a mutable `Iterator`. In addition, however, it also permits modifying the _structure_ of the list by inserting or removing elements at the cursor’s current position.

### Method
`pub fn cursor_back_mut(&mut self) -> CursorMut<'_, T>`
```

--------------------------------

### Use `List` as a LIFO stack

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.List.html

Demonstrates using `List::push_back` and `List::pop_back` to implement a last-in, first-out stack. Elements are added to the back and removed from the back.

```rust
let mut list = List::<Entry>::new();

// Push some entries to the list:
for i in 0..5 {
    list.push_back(Box::pin(Entry::new(i)));
}

// Note that we have reversed the direction of the iterator, since
// we are popping from the *back* of the list:
for i in (0..5).into_iter().rev() {
    let entry = list.pop_back()
        .expect("the list should have 5 entries in it");
    assert_eq!(entry.val, i, "entries are dequeued in LIFO order");
}

assert!(list.is_empty());

```

--------------------------------

### Mutable Cursor at Front

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.List.html

Provides a mutable cursor starting at the first element, allowing iteration and structural modification.

```APIDOC
## cursor_front_mut

### Description
Returns a `CursorMut` starting at the first element.
The `CursorMut` type can be used as a mutable `Iterator`. In addition, however, it also permits modifying the _structure_ of the list by inserting or removing elements at the cursor’s current position.

### Method
`pub fn cursor_front_mut(&mut self) -> CursorMut<'_, T>`
```

--------------------------------

### Create a new SortedList (smallest first)

Source: https://docs.rs/cordyceps/latest/cordyceps/sorted_list/struct.SortedList.html

Creates an empty sorted list where the smallest items are placed first. New values equal to existing ones are placed after old values.

```rust
pub const fn new_min() -> Self
```

--------------------------------

### Get Current Element

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.Cursor.html

Borrows a reference to the element the cursor is currently pointing to. Returns None if the cursor is at the null element.

```rust
pub fn current(&self) -> Option<Pin<&T>>
```

--------------------------------

### CursorCore::move_next - Advance cursor in core

Source: https://docs.rs/cordyceps/latest/src/cordyceps/list/cursor.rs.html

Internal logic for moving the cursor to the next element or to the start if currently null.

```rust
fn move_next(&mut self) {
        match self.curr.take() {
            // Advance the cursor to the current node's next element.
            Some(curr) => unsafe {
                self.curr = T::links(curr).as_ref().next();
                self.index += 1;
            },
            // We have no current element --- move to the start of the list.
            None => {
                self.curr = self.list.head;
                self.index = 0;
            }
        }
    }
```

--------------------------------

### Builder new() and check() Methods

Source: https://docs.rs/cordyceps/latest/src/cordyceps/loom.rs.html

Provides a constructor for the Builder and a method to execute a closure within a tracked environment. Use this to set up and verify allocation tracking in tests.

```rust
impl Builder {
            pub(crate) fn new() -> Self {
                Self::default()
            }

            pub(crate) fn check(&self, f: impl FnOnce()) {
                let registry = super::alloc::track::Registry::default();
                let _tracking = registry.set_default();
                f();
                registry.check();
            }
        }
```

--------------------------------

### Get Cursor Index

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.Cursor.html

Retrieves the current index of the cursor within the list. Returns None if the cursor is positioned at the null element.

```rust
pub fn index(&self) -> Option<usize>
```

--------------------------------

### Stack::new

Source: https://docs.rs/cordyceps/latest/cordyceps/stack/struct.Stack.html

Returns a new, empty Stack.

```APIDOC
## Stack::new

### Description
Returns a new `Stack` with no elements in it.

### Method
`const fn new() -> Self`
```

--------------------------------

### Immutable Cursor from Back

Source: https://docs.rs/cordyceps/latest/cordyceps/struct.List.html

Returns an immutable cursor starting at the last element. This cursor can be used as an iterator and can be seeked to arbitrary positions.

```APIDOC
## cursor_back

### Description
Returns a `Cursor` starting at the last element. The `Cursor` type can be used as `Iterator` over this list. In addition, it may be seeked back and forth to an arbitrary position in the list.

### Method
`pub fn cursor_back(&self) -> Cursor<'_, T>`
```

--------------------------------

### Initialize a new empty List

Source: https://docs.rs/cordyceps/latest/src/cordyceps/list.rs.html

Creates a new, empty `List`. This is a constant function, allowing it to be used in static contexts.

```rust
pub const fn new() -> List<T> {
        List {
            head: None,
            tail: None,
            len: 0,
        }
    }
```

--------------------------------

### Immutable Cursor from Front

Source: https://docs.rs/cordyceps/latest/cordyceps/struct.List.html

Returns an immutable cursor starting at the first element. This cursor can be used as an iterator and can be seeked to arbitrary positions.

```APIDOC
## cursor_front

### Description
Returns a `Cursor` starting at the first element. The `Cursor` type can be used as `Iterator` over this list. In addition, it may be seeked back and forth to an arbitrary position in the list.

### Method
`pub fn cursor_front(&self) -> Cursor<'_, T>`
```

--------------------------------

### take

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.IterMut.html

Creates an iterator that yields at most `n` elements.

```APIDOC
## take(self, n: usize) -> Take<Self>

### Description
Creates an iterator that yields at most the first `n` elements from the underlying iterator. If the underlying iterator yields fewer than `n` elements, all of them will be yielded.

### Method
`take`

### Parameters
#### Path Parameters
- **n** (usize): The maximum number of elements to yield.

### Returns
A new iterator that yields at most `n` elements.
```

--------------------------------

### Get Previous Link

Source: https://docs.rs/cordyceps/latest/src/cordyceps/list.rs.html

Retrieves the previous node in the intrusive list. This is an inline function for performance and requires unsafe access to the inner UnsafeCell.

```rust
#[inline]
fn prev(&self) -> Link<T> {
    unsafe { (*self.inner.get()).prev }
}
```

--------------------------------

### Get Next Link

Source: https://docs.rs/cordyceps/latest/src/cordyceps/list.rs.html

Retrieves the next node in the intrusive list. This is an inline function for performance and requires unsafe access to the inner UnsafeCell.

```rust
#[inline]
fn next(&self) -> Link<T> {
    unsafe { (*self.inner.get()).next }
}
```

--------------------------------

### into

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.IterRaw.html

Calls `U::from(self)`.

```APIDOC
## fn into(self) -> U
where U: From<T>,

### Description
Calls `U::from(self)`. This conversion is whatever the implementation of `From<T> for U` chooses to do.

### Returns
- **U** - The converted value.
```

--------------------------------

### Get Previous Link

Source: https://docs.rs/cordyceps/latest/src/cordyceps/list/cursor.rs.html

Internal helper to retrieve the link to the previous node. If the current node is `None`, it returns the list's tail.

```rust
fn prev_link(&self) -> Link<T> {
        match self.curr {
            Some(curr) => unsafe { T::links(curr).as_ref().prev() },
            None => self.list.tail,
        }
    }
```

--------------------------------

### Get Next Link

Source: https://docs.rs/cordyceps/latest/src/cordyceps/list/cursor.rs.html

Internal helper to retrieve the link to the next node. If the current node is `None`, it returns the list's head.

```rust
fn next_link(&self) -> Link<T> {
        match self.curr {
            Some(curr) => unsafe { T::links(curr).as_ref().next() },
            None => self.list.head,
        }
    }
```

--------------------------------

### take

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.Iter.html

Creates an iterator that yields at most a specified number of elements.

```APIDOC
## fn take(self, n: usize) -> Take<Self>

### Description
Creates an iterator that yields the first `n` elements of the underlying iterator. If the underlying iterator yields fewer than `n` elements, this iterator will yield all of them.

### Method
(Implicitly called on an iterator)

### Parameters
- **n** (usize): The maximum number of elements to yield.

### Returns
A new iterator that yields at most `n` elements.
```

--------------------------------

### DoubleEndedIterator::rfold() Implementation

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.IntoIter.html

Reduces the iterator's elements to a single value, starting from the back. This is useful for accumulating results from the end of a sequence.

```rust
fn rfold<B, F>(self, init: B, f: F) -> B
where Self: Sized, F: FnMut(B, Self::Item) -> B,
```

--------------------------------

### try_into

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.IterMut.html

Performs the conversion.

```APIDOC
## fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
Performs the conversion.
```

--------------------------------

### Thread-local Registry Access

Source: https://docs.rs/cordyceps/latest/src/cordyceps/loom.rs.html

Provides thread-local access to the current allocation tracking Registry. Use `current()` to get the active registry on the current thread.

```rust
thread_local! {
                static REGISTRY: RefCell<Option<Registry>> = const { RefCell::new(None) };
            }

            impl Registry {
                pub(in crate::loom) fn current() -> Option<Registry> {
                    REGISTRY.with(|current| current.borrow().clone())
                }

                // ... other methods
```

--------------------------------

### take

Source: https://docs.rs/cordyceps/latest/cordyceps/sorted_list/struct.SortedListIter.html

Creates an iterator that yields the first `n` elements, or fewer if the underlying iterator ends sooner.

```APIDOC
## fn take(self, n: usize) -> Take<Self>

### Description
Creates an iterator that yields the first `n` elements, or fewer if the underlying iterator ends sooner.

### Method
`take`
```

--------------------------------

### Create a new empty list

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.List.html

Initializes a new, empty instance of the `List` struct.

```rust
pub const fn new() -> List<T>
```

--------------------------------

### Mutable Cursor from Back

Source: https://docs.rs/cordyceps/latest/cordyceps/struct.List.html

Returns a mutable cursor starting at the last element. This cursor can be used as a mutable iterator and allows structural modifications to the list.

```APIDOC
## cursor_back_mut

### Description
Returns a `CursorMut` starting at the last element. The `CursorMut` type can be used as a mutable `Iterator`. In addition, however, it also permits modifying the _structure_ of the list by inserting or removing elements at the cursor’s current position.

### Method
`pub fn cursor_back_mut(&mut self) -> CursorMut<'_, T>`
```

--------------------------------

### Create a SortedList from a Stack (least first)

Source: https://docs.rs/cordyceps/latest/src/cordyceps/sorted_list.rs.html

Constructs a sorted list from an existing `Stack`, ordering elements from smallest to largest. Elements are sorted using the default `Ord` implementation. New elements equal to existing ones are placed after.

```rust
pub fn from_stack_min(stack: Stack<T>) -> Self {
    Self::from_stack_with_cmp(stack, T::cmp)
}
```

--------------------------------

### List Extension Methods

Source: https://docs.rs/cordyceps/latest/cordyceps/list/struct.List.html

Methods for adding elements to the List.

```APIDOC
## fn extend<I: IntoIterator<Item = T::Handle>>(&mut self, iter: I)

### Description
Extends a collection with the contents of an iterator.

### Method
`extend`

### Parameters
- `iter`: An iterator whose items will be added to the list.
```

```APIDOC
## fn extend_one(&mut self, item: A)

### Description
Extends a collection with exactly one element. This is a nightly-only experimental API.

### Method
`extend_one`

### Parameters
- `item`: The element to add to the list.
```

```APIDOC
## fn extend_reserve(&mut self, additional: usize)

### Description
Reserves capacity in a collection for the given number of additional elements. This is a nightly-only experimental API.

### Method
`extend_reserve`

### Parameters
- `additional`: The number of additional elements to reserve capacity for.
```

--------------------------------

### Mutable Cursor from Front

Source: https://docs.rs/cordyceps/latest/cordyceps/struct.List.html

Returns a mutable cursor starting at the first element. This cursor can be used as a mutable iterator and allows structural modifications to the list.

```APIDOC
## cursor_front_mut

### Description
Returns a `CursorMut` starting at the first element. The `CursorMut` type can be used as a mutable `Iterator`. In addition, however, it also permits modifying the _structure_ of the list by inserting or removing elements at the cursor’s current position.

### Method
`pub fn cursor_front_mut(&mut self) -> CursorMut<'_, T>`
```

--------------------------------

### FmtOption struct and its Debug/Display implementations

Source: https://docs.rs/cordyceps/latest/src/cordyceps/util.rs.html

A wrapper for Option types to customize their debug and display formatting. It allows specifying a custom string to use when the Option is None.

```rust
pub(crate) struct FmtOption<'a, T> {
    opt: Option<&'a T>,
    or_else: &'a str,
}

// === impl FmtOption ===

impl<'a, T> FmtOption<'a, T> {
    pub(crate) fn new(opt: &'a Option<T>) -> Self {
        Self {
            opt: opt.as_ref(),
            or_else: "None",
        }
    }
}

impl<T: fmt::Debug> fmt::Debug for FmtOption<'_, T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self.opt {
            Some(val) => val.fmt(f),
            None => f.write_str(self.or_else),
        }
    }
}

impl<T: fmt::Display> fmt::Display for FmtOption<'_, T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self.opt {
            Some(val) => val.fmt(f),
            None => f.write_str(self.or_else),
        }
    }
}
```

--------------------------------

### Get Current Node Reference

Source: https://docs.rs/cordyceps/latest/src/cordyceps/list/cursor.rs.html

Returns an optional pinned reference to the current node. This is used for consistent API behavior across mutable and immutable cursors.

```rust
fn current(&self) -> Option<Pin<&T>> {
        // NOTE(eliza): in this case, we don't *need* to pin the reference,
        // because it's immutable and you can't move out of a shared
        // reference in safe code. but...it makes the API more consistent
        // with `front_mut` etc.
        self.curr.map(|node| unsafe { self.pin_node(node) })
    }
```

--------------------------------

### Cursor::index - Get current index

Source: https://docs.rs/cordyceps/latest/src/cordyceps/list/cursor.rs.html

Returns the index of the cursor's current position in the list. Returns None if the cursor points to the null element.

```rust
pub fn index(&self) -> Option<usize> {
        self.core.index()
    }
```

--------------------------------

### Verify Links Send and Sync

Source: https://docs.rs/cordyceps/latest/src/cordyceps/stack.rs.html

Uses a utility function to assert that `Links<Entry>` implements the `Send` and `Sync` traits.

```rust
crate::util::assert_send_sync::<Links<Entry>>();
```
Tokens:
Raw