Quark

Generic link-time registry infrastructure for Rust.

Quark provides a Registrable trait, an owned Registry<T>, and a define_registry! macro for building type-safe registries backed by inventory link-time collection.

Status: v0.1.1 early release · MIT · GitHub

Performance (see study): lookups ~15 ns at 10k entries; compile scales ~linearly with inventory::submit! count.

Mental model

• Type-safe registries with minimal boilerplate
• Link-time collection via inventory::submit! (per consumer crate)
• Owned registry instances (no global Mutex)
• quark::inventory re-export keeps inventory versions in sync across consumers

Quick start

Define a descriptor and make it registrable:

use quark::Registrable;

pub struct ScriptDescriptor {
    pub name: &'static str,
}

inventory::collect!(ScriptDescriptor);

impl Registrable for ScriptDescriptor {
    fn registry_key(&self) -> &str { self.name }
}

Define a typed registry:

quark::define_registry! {
    pub struct ScriptRegistry for ScriptDescriptor;
}

impl ScriptRegistry {
    pub fn get_or_err(&self, name: &str) -> Result<&'static ScriptDescriptor, String> {
        self.get(name).ok_or_else(|| format!("script '{}' not found", name))
    }
}

Discover at startup:

let registry = ScriptRegistry::auto_discover();
let script = registry.get("daily_reset").unwrap();

Example use cases

Downstream crates should depend on quark and import quark::inventory (the re-export) rather than adding a separate inventory dependency.

Examples

Runnable walkthroughs, from single-file basics to a two-crate plugin host proving cross-crate link-time discovery: examples/README.md.

cargo run --example registry_basics   # Registrable + auto_discover + duplicate keys
cargo run --example macro_registry    # define_registry! newtype + Deref
cargo run -p plugin-host              # cross-crate plugin discovery

Compile-scale fixtures

When you need to measure how inventory compile cost scales with registry size — before adopting Quark in a macro-heavy crate — use the generated packages under benches/compile-scale/. Each quark-scale-{N}/ crate contains N inventory::submit! entries (tiers: 1, 10, 100, 500, 1000, 5000, 10000).

Regenerate tiers:

bash benches/compile-scale/generate.sh

Cold build sweep:

./scripts/bench-compile-scale.sh

Incremental scenarios:

./scripts/bench-incremental-scale.sh

These are manual / scheduled benchmarks — not part of default CI. See benches/compile-scale/README.md and docs/PERFORMANCE_STUDY.md for methodology.

Development

cargo test
cargo bench --bench runtime
cargo doc --no-deps

Documentation

License

MIT (see LICENSE).