active-uuid-registry 0.8.0

A library for managing in-process, context-aware UUIDs for liveness tracking.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

//! # Active UUID Registry
//! 
//! A library for managing in-process, system-wide `UUID`s for tracking component liveness.
//! 
//! This library provides a thread-safe UUID pool that can be used to track the liveness of UUIDs.
//! 
//! UUIDs are organized in a two-level global registry (`namespace -> context -> UUID set`), making it straightforward to track running components across logical scopes in dynamic systems.
//! 
//! Strongly encouraged to use proper management and implementation practices for their particular process/use-case, as there is no garbage collection or pool monitoring on the part of this library.
//! 
//! Use at your own (possible but unlikely) risk. *You* are responsible for managing the pool and its contents.
//! 
//! # Feature Flags
//! 
//! - **Default / single-threaded**: Use a single-threaded map for the UUID pool.
//!   - Uses a `parking_lot::Mutex<HashMap<NamespaceKey, HashMap<ContextKey, HashSet<Uuid>>>>` for the UUID pool.
//! - **concurrent-map**: Use a concurrent map for the UUID pool.
//!   - Uses a `DashMap<NamespaceKey, DashMap<ContextKey, DashSet<Uuid>>>` for the UUID pool.
//! 


mod registry;

/// Interface API module for the Active UUID Registry.
pub mod interface;

mod raii;

/// A cloneable, opaque write-authorization capability for a namespace claimed via
/// [`interface::reserve_owned_namespace`].
pub use raii::OwnedNamespace;

#[doc(inline)]
pub use uuid as registry_uuid;  

/// Represents the name of a namespace within the registry pool.
pub type NamespaceString = String;

/// Represents the name of a context within the registry pool.
pub type ContextString = String;

/// Error type for UUID pool operations.
#[derive(Debug, thiserror::Error, Clone, PartialEq, Eq, Hash)]
pub enum UuidPoolError {
    #[error("Failed to generate unique UUID: {0}")]
    FailedToGenerateUniqueUuidError(String),
    #[error("Failed to find UUID in pool: {0}")]
    FailedToFindUuidInPoolError(String),
    #[error("Failed to set UUID in pool: {0}")]
    FailedToSetUuidInPoolError(String),
    #[error("Failed to add UUID to pool: {0}")]
    FailedToAddUuidToPoolError(String),
    #[error("Failed to remove UUID from pool: {0}")]
    FailedToRemoveUuidFromPoolError(String),
    #[error("Failed to replace UUID in pool: {0}")]
    FailedToReplaceUuidInPoolError(String),
    #[error("Unauthorized write access to namespace '{0}'")]
    UnauthorizedNamespaceWriteAccessError(String),
    #[error("Failed to claim owned namespace: {0}")]
    FailedToClaimNamespaceError(String),
}