Crate scattered_collect

Expand description

§Scattered Collections

The crate is part of the linktime project.

crate		docs	version
`linktime`	Convenience crate for `ctor`, `dtor` and `link-section`
`ctor`	Module initialization functions before main
`dtor`	Module shutdown functions before main
`link-section`	Linker-managed typed (slices) and untyped sections
`scattered-collect`	Linker-managed collections: slices, sorted slices, maps

A crate for defining linker-managed scattered collections in Rust.

The collections come in a ‘referenced’ and ‘unreferenced’ variant. The referenced variants allow you to access the items as static handles at the declaration site, while the unreferenced variants allow you to access the items as a slice only. The latter, unreferenced variants may be more efficient.

§Zero-allocation collections

The collections are all zero-allocation. This means that they can be used in no-std/no-alloc environments, and that they do not contribute to heap usage whatsoever.

§Collections

ScatteredIterable: A collection of items that are available only via iterator.
ScatteredSlice: A collection of sized items that collected into a slice in an arbitrary order.
ScatteredSortedSlice: A collection of items that are available via slice, in sorted order.
ScatteredReferencedSlice: A collection of items collected into a slice (link order), with each static item auto-wrapped as referenced_slice::Ref.
ScatteredSortedReferencedSlice: A collection of sized items that are available both via sorted slice and via reference at the declaration site (auto-wrapped as sorted_referenced_slice::Ref).
ScatteredMap: A collection of key-value pairs that are available via slice, as well as indexed by key.

§Scatter/Gather syntax

The collections are defined as a single scatter call with multiple gather calls that submit items to the collection.

#[gather]
static COLLECTION: ScatteredSlice<DatabaseDriver>;

… and then elsewhere in your crate:


mod postgres {
    #[scatter(COLLECTION)]
    static POSTGRES_DRIVER: DatabaseDriver = DatabaseDriver("postgres" /*, ...*/);
}

mod mysql {
    #[scatter(COLLECTION)]
    static MYSQL_DRIVER: DatabaseDriver = DatabaseDriver("mysql" /*, ...*/);
}

Re-exports§

pub use iterable::ScatteredIterable;
pub use map::ScatteredMap;
pub use referenced_slice::ScatteredReferencedSlice;
pub use slice::ScatteredSlice;
pub use sorted_referenced_slice::ScatteredSortedReferencedSlice;
pub use sorted_slice::ScatteredSortedSlice;

Modules§

declarative: Declarative scatter! / gather! entry points.
hash: Hash functions for compile-time hashing.
iterable: A collection of items linked at runtime into a singly-linked list in constructor order.
map: A swiss-table-style lookup table initialized with link-time data.
referenced_slice: A collection of items gathered into a slice (link order), with each entry wrapped as Ref so static items work on targets such as WASM.
slice: A collection of sized items gathered into a slice in arbitrary link order.
sorted_referenced_slice: A collection of sized items available both as a sorted slice and as stable handles at each declaration site.
sorted_slice: A collection of items available via sorted slice.

Macros§

const_hash: Hash a value at compile time. To implement ConstHash for a type, you must provide a type that has a const fn const_hash() method.

Attribute Macros§

gather: Builds the sorted slice type over a scattered collection.
scatter: Registers one value into a scattered collection.