Crate scattered_collect

Expand description

§Scattered Collections

The crate is part of the linktime project.

crate
`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.

§MSRV

This crate currently has a MSRV of Rust >= 1.85.

For collections that have duplicate names across different files, Rust >= 1.88 is required (the proc_macro_span is used to generate unique filenames).

§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.

§Free ID generation

Each item is placed in a section which allows for free identifier generation. Use each collection’s offset_of method to get the offset of an item in the collection. This ID is guaranteed to be stable per executable build.

§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.

Collection	Ordering	Indexed Access	Unique Keys	Per-Item Handles	Notes
`ScatteredSlice`	Arbitrary (link order)	Yes (slice)	No †	No	Basic un-ordered slice
`ScatteredSortedSlice`	Sorted	Yes (slice)	No †	No	Sorted slice
`ScatteredIterable`	Arbitrary (link order)	No (iterator only)	No †	Yes	Singly-linked list
`ScatteredReferencedSlice`	Arbitrary (link order)	Yes (slice)	No †	Yes	Un-ordered slice with handles
`ScatteredSortedReferencedSlice`	Sorted	Yes (slice)	No †	Yes	Sorted slice with handles
`ScatteredMap`	None (link order)	Yes (by key or entry)	Yes	Yes	Swiss-table style map
`ScatteredSet`	None (link order)	n/a	Yes	No	Swiss-table style set

† Each item in the collection is assigned a unique ID which is guaranteed to be stable per executable build.

§Re-exporting the scatter/gather macros

If you wrap these collections in your own library so that downstream users don’t need to depend on scattered-collect directly, you have two options.

The (preferred) option is to re-export the declarative forms of the macros. They resolve their support paths back to scattered-collect through the re-exporting crate, so no extra configuration is needed:

// In your library crate:
pub use scattered_collect::declarative::{gather, scatter};
pub use scattered_collect::slice::ScatteredSlice;

Downstream users then invoke them as gather! { #[gather] ... } and scatter! { #[scatter(COLLECTION)] ... }.

Alternatively, the proc-macro #[scatter] / #[gather] attribute forms emit a fixed ::scattered_collect path and so require a direct dependency by default. Pass crate_path = <path> to redirect them to wherever scattered-collect has been re-exported:

#[gather(crate_path = ::scattered_collect)]
static ITEMS: ScatteredSlice<u32>;

#[scatter(crate_path = ::scattered_collect, ITEMS)]
const _: u32 = 1;

§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 set::ScatteredSet;
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.
set: A swiss-table-style set initialized with link-time data.
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
scatter