glitcher_core/

registry.rs

use std::collections::HashMap;
use std::marker::PhantomData;
use thiserror::Error;

#[derive(Debug, Error)]
pub enum RegistryError {
    #[error("Registry capacity exceeded")]
    CapacityExceeded,
    #[error("Handler '{0}' already exists")]
    AlreadyExists(String),
    #[error("Slot generation exhausted")]
    SlotExhausted,
    #[error("Memory allocation failed: {0}")]
    AllocationFailed(String),
}

/// A lightweight, copyable handle acting as a safe pointer.
pub struct HandlerId<T> {
    pub(crate) index: u32,
    pub(crate) generation: u32,
    pub(crate) _marker: PhantomData<T>,
}

// Manual implementations to avoid T: Trait bounds
impl<T> Clone for HandlerId<T> {
    fn clone(&self) -> Self {
        *self
    }
}

impl<T> Copy for HandlerId<T> {}

impl<T> PartialEq for HandlerId<T> {
    fn eq(&self, other: &Self) -> bool {
        self.index == other.index && self.generation == other.generation
    }
}

impl<T> Eq for HandlerId<T> {}

impl<T> std::hash::Hash for HandlerId<T> {
    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
        self.index.hash(state);
        self.generation.hash(state);
    }
}

impl<T> std::fmt::Debug for HandlerId<T> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("HandlerId")
            .field("index", &self.index)
            .field("generation", &self.generation)
            .finish()
    }
}

struct Slot<T> {
    item: Option<T>,
    generation: u32,
    name: Option<String>,
}

/// A strict, capacity-limited registry that separates Cold Path (registration)
/// from Hot Path (access) to ensure consistent performance.
pub struct Registry<T> {
    slots: Vec<Slot<T>>,
    free_indices: Vec<usize>,
    name_map: HashMap<String, usize>,
    capacity: usize,
}

impl<T> Registry<T> {
    /// Creates a new registry with a fixed capacity.
    /// Pre-allocates all necessary memory to avoid runtime allocations.
    pub fn new(capacity: usize) -> Result<Self, RegistryError> {
        let mut slots = Vec::new();
        if let Err(e) = slots.try_reserve(capacity) {
            return Err(RegistryError::AllocationFailed(e.to_string()));
        }

        // Initialize slots with empty state to avoid runtime resizing
        for _ in 0..capacity {
            slots.push(Slot {
                item: None,
                generation: 0,
                name: None,
            });
        }

        let mut free_indices = Vec::new();
        if let Err(e) = free_indices.try_reserve(capacity) {
            return Err(RegistryError::AllocationFailed(e.to_string()));
        }

        // Fill free indices in reverse order so we use index 0 first
        for i in (0..capacity).rev() {
            free_indices.push(i);
        }

        let mut name_map = HashMap::new();
        if let Err(e) = name_map.try_reserve(capacity) {
            return Err(RegistryError::AllocationFailed(e.to_string()));
        }

        Ok(Self {
            slots,
            free_indices,
            name_map,
            capacity,
        })
    }

    /// [Cold Path] Registers an item with a string ID.
    /// Fails if capacity is exceeded or name already exists.
    pub fn register(
        &mut self,
        name: impl Into<String>,
        item: T,
    ) -> Result<HandlerId<T>, RegistryError> {
        let name = name.into();
        if self.name_map.contains_key(&name) {
            return Err(RegistryError::AlreadyExists(name));
        }

        // Pop a free index. If empty, we are at capacity.
        let index = self
            .free_indices
            .pop()
            .ok_or(RegistryError::CapacityExceeded)?;

        let slot = &mut self.slots[index];

        // Safety Check: Generation overflow
        if slot.generation == u32::MAX {
            return Err(RegistryError::SlotExhausted);
        }

        slot.item = Some(item);
        slot.name = Some(name.clone());

        // Map name -> index
        self.name_map.insert(name, index);

        Ok(HandlerId {
            index: index as u32,
            generation: slot.generation,
            _marker: PhantomData,
        })
    }

    /// [Hot Path] Access item by ID (No allocation, O(1))
    #[inline]
    pub fn get(&self, id: HandlerId<T>) -> Option<&T> {
        if let Some(slot) = self.slots.get(id.index as usize) {
            if slot.generation == id.generation {
                return slot.item.as_ref();
            }
        }
        None
    }

    /// [Hot Path] Mutable access item by ID (No allocation, O(1))
    #[inline]
    pub fn get_mut(&mut self, id: HandlerId<T>) -> Option<&mut T> {
        if let Some(slot) = self.slots.get_mut(id.index as usize) {
            if slot.generation == id.generation {
                return slot.item.as_mut();
            }
        }
        None
    }

    /// [Cold Path] Look up a handler ID by name
    pub fn lookup(&self, name: &str) -> Option<HandlerId<T>> {
        if let Some(&index) = self.name_map.get(name) {
            if let Some(slot) = self.slots.get(index) {
                // Validity check, though name_map should generally be consistent
                if slot.item.is_some() {
                    return Some(HandlerId {
                        index: index as u32,
                        generation: slot.generation,
                        _marker: PhantomData,
                    });
                }
            }
        }
        None
    }

    /// [Cold Path] Remove an item by ID.
    /// Updates generation to invalidate old handles and cleans up name map.
    pub fn remove(&mut self, id: HandlerId<T>) -> Option<T> {
        if let Some(slot) = self.slots.get_mut(id.index as usize) {
            if slot.generation == id.generation {
                // 1. Increment generation to invalidate old handles
                slot.generation = slot.generation.wrapping_add(1);

                // 2. Remove item
                let item = slot.item.take();

                // 3. Clean up name map using stored name
                if let Some(name) = slot.name.take() {
                    self.name_map.remove(&name);
                }

                // 4. Return index to free list
                self.free_indices.push(id.index as usize);

                return item;
            }
        }
        None
    }

    /// Returns the fixed capacity of the registry.
    pub fn capacity(&self) -> usize {
        self.capacity
    }

    /// Returns the current number of items.
    pub fn count(&self) -> usize {
        self.capacity - self.free_indices.len()
    }

    /// Returns an iterator over all registered names.
    pub fn keys(&self) -> impl Iterator<Item = &String> {
        self.name_map.keys()
    }

    /// Returns an iterator over all registered items with their names.
    pub fn iter(&self) -> impl Iterator<Item = (&String, &T)> {
        self.slots.iter().filter_map(|slot| {
            if let (Some(name), Some(item)) = (&slot.name, &slot.item) {
                Some((name, item))
            } else {
                None
            }
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_capacity_limit() {
        let mut registry = Registry::<i32>::new(2).unwrap();

        assert!(registry.register("a", 1).is_ok());
        assert!(registry.register("b", 2).is_ok());

        let result = registry.register("c", 3);
        assert!(matches!(result, Err(RegistryError::CapacityExceeded)));
    }

    #[test]
    fn test_access_by_id() {
        let mut registry = Registry::<String>::new(10).unwrap();
        let id = registry.register("test", "Hello".to_string()).unwrap();

        assert_eq!(registry.get(id).unwrap(), "Hello");
        assert_eq!(registry.get_mut(id).unwrap(), "Hello");

        *registry.get_mut(id).unwrap() = "World".to_string();
        assert_eq!(registry.get(id).unwrap(), "World");
    }

    #[test]
    fn test_removal_and_generation() {
        let mut registry = Registry::<i32>::new(10).unwrap();
        let id1 = registry.register("item", 100).unwrap();

        // Remove it
        let val = registry.remove(id1);
        assert_eq!(val, Some(100));

        // Old ID should be invalid
        assert!(registry.get(id1).is_none());

        // Register new item (likely reuses same slot)
        let id2 = registry.register("item2", 200).unwrap();

        // If it reused the slot (index 0), indices match but generations differ
        if id1.index == id2.index {
            assert_ne!(id1.generation, id2.generation);
        }

        // Old ID still invalid for new item
        assert!(registry.get(id1).is_none());
        assert_eq!(registry.get(id2).unwrap(), &200);
    }

    #[test]
    fn test_name_map_consistency() {
        let mut registry = Registry::<i32>::new(10).unwrap();
        let id = registry.register("my_item", 123).unwrap();

        // Lookup works
        let looked_up_id = registry.lookup("my_item").unwrap();
        assert_eq!(id, looked_up_id);

        // Remove by ID
        registry.remove(id);

        // Lookup should fail
        assert!(registry.lookup("my_item").is_none());

        // Register with same name should work now
        assert!(registry.register("my_item", 456).is_ok());
    }

    #[test]
    fn test_duplicate_name() {
        let mut registry = Registry::<i32>::new(10).unwrap();
        registry.register("dup", 1).unwrap();

        let result = registry.register("dup", 2);
        assert!(matches!(result, Err(RegistryError::AlreadyExists(_))));
    }
}