singleton-registry

A thread-safe singleton registry for Rust.
Create isolated registries for storing and retrieving any type.
Each type can have only one instance per registry.

⚠️ Breaking Change in v2.0: This version uses a macro-based API. If you're upgrading from v1.x, you'll need to use define_registry! to create registries instead of using global functions. See the Quick Start below for the new API.

Features & Design

• Synchronous API: No async/await complexity - simple function calls
• Thread-safe: All operations safe across multiple threads using Arc and Mutex
• Isolated registries: Create multiple independent registries with define_registry! - no hidden globals
• True singleton: Only one instance per type per registry
• Write-once pattern: Designed for initialization-time registration with optional runtime overrides
• No removal: Values can be overridden but not removed - provide default values for fail-safe operation
• Override-friendly: Later registrations replace previous ones
• Tracing support: Optional callback system for monitoring operations

Quick Start

use singleton_registry::define_registry;
use std::sync::Arc;

define_registry!(global);
define_registry!(cache);

global::register("Hello, World!".to_string());
cache::register(42i32);

let message: Arc<String> = global::get().unwrap();
let number: Arc<i32> = cache::get().unwrap();

assert_eq!(&*message, "Hello, World!");
assert_eq!(*number, 42);

Advanced Usage

use singleton_registry::define_registry;
use std::sync::Arc;

define_registry!(app);

app::set_trace_callback(|event| {
    println!("Registry event: {}", event);
});

app::register(12i32);
app::register("config".to_string());

let multiply_by_two: fn(i32) -> i32 = |x| x * 2;
app::register(multiply_by_two);

assert!(app::contains::<i32>().unwrap());

let number: Arc<i32> = app::get().unwrap();
let config: Arc<String> = app::get().unwrap();
let doubler: Arc<fn(i32) -> i32> = app::get().unwrap();

let result = doubler(21);

assert_eq!(result, 42);
assert_eq!(*number, 12);
assert_eq!(&*config, "config");

Multiple Isolated Registries

use singleton_registry::define_registry;

define_registry!(database);
define_registry!(cache);
define_registry!(config);

database::register("postgresql://localhost".to_string());
cache::register("redis://localhost".to_string());
config::register("app_config".to_string());

let db_conn = database::get::<String>().unwrap();
let cache_conn = cache::get::<String>().unwrap();

API Reference

Each registry created with define_registry!(name) provides:

• name::register(value) - Register a value
• name::register_arc(arc_value) - Register an Arc-wrapped value
• name::get::<T>() - Retrieve a value as Arc<T> (returns Result)
• name::get_cloned::<T>() - Retrieve a cloned value (requires Clone, returns Result)
• name::contains::<T>() - Check if a type is registered (returns Result)
• name::set_trace_callback(callback) - Set up tracing
• name::clear_trace_callback() - Clear tracing

Error Handling

All fallible operations return Result<T, RegistryError>:

pub enum RegistryError {
    /// Type not found in the registry
    TypeNotFound { type_name: &'static str },

    /// Type mismatch during retrieval (should never happen)
    TypeMismatch { type_name: &'static str },

    /// Failed to acquire registry lock (automatically recovered)
    RegistryLock,
}

Example:

use singleton_registry::define_registry;

define_registry!(app);

// Handle errors explicitly
match app::get::<String>() {
    Ok(value) => println!("Found: {}", value),
    Err(e) => eprintln!("Error: {}", e),  // "Type not found in registry: alloc::string::String"
}

// Or use ? operator
fn get_config() -> Result<std::sync::Arc<String>, singleton_registry::RegistryError> {
    app::get::<String>()
}

Note on Lock Poisoning: The registry automatically recovers from poisoned locks by extracting the inner value. This is safe because registry operations are idempotent.

Use Cases

• Application singletons (Config, Logger, DatabasePool, etc.)
• Isolated contexts (per-module registries, test isolation)
• Function helpers and utility closures
• Shared resources and components
• Service locator pattern with type safety

Best Practice: Register all required types during initialization-time to ensure get() never fails during runtime.

Roadmap

v2.1.0 (Planned)

• try_register() - Explicit error handling for registration operations
• Enhanced documentation - Add "Limitations" section and comparison with alternatives
• Benchmarks - Document performance characteristics
• Lock poisoning tests - Verify recovery behavior under stress

Future Considerations

• get_or_default() - Convenience method with fallback values
• get_or_init() - Lazy initialization support
• register_if_absent() - Conditional registration

Non-Goals

• Async support (keeping it synchronous by design)
• Removal operations (override-only by design)

See CHANGELOG.md for version history and CONTRIBUTING.md for contribution guidelines.

Installation

Add this to your Cargo.toml:

[dependencies]
singleton-registry = "2.0"

License

BSD-3-Clause