pub unsafe trait Adapter {
    type EntryType: ?Sized;

    fn to_links(obj: &Self::EntryType) -> &Links<Self::EntryType>;
}
Expand description

A linked-list adapter.

It is a separate type (as opposed to implemented by the type of the elements of the list) so that a given type can be inserted into multiple lists at the same time; in such cases, each list needs its own adapter that returns a different pointer to links.

It may, however, be implemented by the type itself to be inserted into lists, which makes it more readable.

Safety

Implementers must ensure that the links returned by Adapter::to_links are unique to the adapter. That is, different adapters must return different links for a given object.

The reason for this requirement is to avoid confusion that may lead to UB. In particular, if two adapters were to use the same links, a user may have two lists (one for each adapter) and try to insert the same object into both at the same time; although this clearly violates the list safety requirements (e.g., those in List::push_back), for users to notice it, they’d have to dig into the details of the two adapters.

By imposing the requirement on the adapter, we make it easier for users to check compliance with the requirements when using the list.

Examples


struct Example {
    a: u32,
    b: u32,
    links1: Links<Example>,
    links2: Links<Example>,
}

// SAFETY: This adapter is the only one that uses `Example::links1`.
unsafe impl Adapter for Example {
    type EntryType = Self;
    fn to_links(obj: &Self) -> &Links<Self> {
        &obj.links1
    }
}

struct ExampleAdapter;

// SAFETY: This adapter is the only one that uses `Example::links2`.
unsafe impl Adapter for ExampleAdapter {
    type EntryType = Example;
    fn to_links(obj: &Example) -> &Links<Example> {
        &obj.links2
    }
}

static LIST1: List<Example> = List::new();
static LIST2: List<ExampleAdapter> = List::new();

Required Associated Types

The type of the enties in the list.

Required Methods

Retrieves the linked list links for the given object.

Implementors

This documentation is an old archive. Please see https://rust.docs.kernel.org instead.