fastalloc 1.5.0

High-performance memory pooling library with type-safe handles, predictable latency, and zero fragmentation. Perfect for game engines, real-time systems, and high-churn workloads.
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
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

//! Shared handle with reference counting for pool-allocated objects.

use alloc::rc::Rc;
use core::fmt;
use core::ops::Deref;

/// A shared handle to a pool-allocated object with reference counting.
///
/// Multiple `SharedHandle` instances can point to the same object.
/// The object is returned to the pool only when the last handle is dropped.
///
/// # Examples
///
/// ```rust
/// use fastalloc::{FixedPool, SharedHandle};
///
/// let pool = FixedPool::<i32>::new(10).unwrap();
/// // Note: This is a simplified example. Actual implementation would need
/// // pool support for shared handles.
/// ```
///
/// # Note
///
/// This is currently a placeholder implementation. Full reference-counted
/// handles require additional pool infrastructure.
pub struct SharedHandle<'pool, T> {
    pub(crate) inner: Rc<SharedHandleInner<'pool, T>>,
}

pub(crate) struct SharedHandleInner<'pool, T> {
    pub(crate) pool: &'pool dyn super::owned::PoolInterface<T>,
    pub(crate) index: usize,
    pub(crate) _marker: core::marker::PhantomData<T>,
}

impl<'pool, T> SharedHandle<'pool, T> {
    /// Creates a new shared handle.
    ///
    /// This is internal and should only be called by pool implementations.
    #[inline]
    #[allow(dead_code)]
    pub(crate) fn new(pool: &'pool dyn super::owned::PoolInterface<T>, index: usize) -> Self {
        Self {
            inner: Rc::new(SharedHandleInner {
                pool,
                index,
                _marker: core::marker::PhantomData,
            }),
        }
    }

    /// Returns the number of shared handles pointing to this object.
    #[inline]
    pub fn strong_count(&self) -> usize {
        Rc::strong_count(&self.inner)
    }

    /// Returns the internal index of this handle.
    #[inline]
    pub fn index(&self) -> usize {
        self.inner.index
    }

    /// Creates a weak handle from this shared handle.
    pub fn downgrade(&self) -> super::WeakHandle<'pool, T> {
        super::WeakHandle::new(Rc::downgrade(&self.inner))
    }
}

impl<'pool, T> Clone for SharedHandle<'pool, T> {
    fn clone(&self) -> Self {
        Self {
            inner: Rc::clone(&self.inner),
        }
    }
}

impl<'pool, T> Deref for SharedHandle<'pool, T> {
    type Target = T;

    #[inline]
    fn deref(&self) -> &Self::Target {
        self.inner.pool.get(self.inner.index)
    }
}

impl<'pool, T> Drop for SharedHandleInner<'pool, T> {
    fn drop(&mut self) {
        // Return to pool when the last reference is dropped
        self.pool.return_to_pool(self.index);
    }
}

impl<'pool, T: fmt::Debug> fmt::Debug for SharedHandle<'pool, T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("SharedHandle")
            .field("index", &self.inner.index)
            .field("strong_count", &self.strong_count())
            .field("value", &**self)
            .finish()
    }
}

impl<'pool, T: fmt::Display> fmt::Display for SharedHandle<'pool, T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Display::fmt(&**self, f)
    }
}

impl<'pool, T: PartialEq> PartialEq for SharedHandle<'pool, T> {
    fn eq(&self, other: &Self) -> bool {
        **self == **other
    }
}

impl<'pool, T: Eq> Eq for SharedHandle<'pool, T> {}

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

    #[test]
    fn shared_handle_clone() {
        let pool = FixedPool::<i32>::new(10).unwrap();
        let handle = pool.allocate(42).unwrap();
        let index = handle.index();

        // Convert to shared handle (note: this bypasses normal pool lifecycle)
        let shared = SharedHandle::new(&pool, index);
        assert_eq!(shared.strong_count(), 1);

        let shared2 = shared.clone();
        assert_eq!(shared.strong_count(), 2);
        assert_eq!(shared2.strong_count(), 2);

        drop(shared2);
        assert_eq!(shared.strong_count(), 1);

        // Prevent double-free by forgetting the original handle
        core::mem::forget(handle);
    }
}