Crate scattered_collect 

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.

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

The scatter/gather macros can be easily re-exported from other crates using the declarative module.

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