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

//! Weak handle that doesn't prevent object return to pool.

use alloc::rc::Weak;
use core::fmt;

/// A weak handle to a pool-allocated object.
///
/// Weak handles do not contribute to the reference count and do not
/// prevent the object from being returned to the pool. They can be
/// upgraded to a `SharedHandle` if the object is still alive.
///
/// # Examples
///
/// ```rust
/// use fastalloc::{FixedPool, SharedHandle};
///
/// let pool = FixedPool::<i32>::new(10).unwrap();
/// // This is a simplified example showing the concept
/// ```
pub struct WeakHandle<'pool, T> {
    inner: Weak<super::shared::SharedHandleInner<'pool, T>>,
}

impl<'pool, T> WeakHandle<'pool, T> {
    /// Creates a new weak handle from a weak reference.
    ///
    /// This is internal and should only be called by `SharedHandle::downgrade()`.
    #[inline]
    pub(crate) fn new(inner: Weak<super::shared::SharedHandleInner<'pool, T>>) -> Self {
        Self { inner }
    }

    /// Attempts to upgrade this weak handle to a shared handle.
    ///
    /// Returns `None` if the object has already been returned to the pool.
    #[inline]
    pub fn upgrade(&self) -> Option<super::SharedHandle<'pool, T>> {
        self.inner
            .upgrade()
            .map(|inner| super::SharedHandle { inner })
    }

    /// Returns the number of strong references to the object, if it still exists.
    #[inline]
    pub fn strong_count(&self) -> usize {
        self.inner.strong_count()
    }

    /// Returns the number of weak references to the object.
    #[inline]
    pub fn weak_count(&self) -> usize {
        self.inner.weak_count()
    }
}

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

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

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

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

        let shared = SharedHandle::new(&pool, index);
        let weak = shared.downgrade();

        assert_eq!(weak.strong_count(), 1);

        // Can upgrade while shared handle exists
        let upgraded = weak.upgrade();
        assert!(upgraded.is_some());
        assert_eq!(weak.strong_count(), 2);

        drop(shared);
        drop(upgraded);

        // Cannot upgrade after all strong references are gone
        let upgraded = weak.upgrade();
        assert!(upgraded.is_none());

        // Prevent double-free
        core::mem::forget(handle);
    }

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

        let shared = SharedHandle::new(&pool, index);
        let weak = shared.downgrade();
        let weak2 = weak.clone();

        assert_eq!(weak.weak_count(), weak2.weak_count());

        // Cleanup
        drop(shared);
        core::mem::forget(handle);
    }
}