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

//! Traits for working with memory pools.

use crate::error::Result;

/// A trait for types that can be used with memory pools.
///
/// This trait provides hooks for custom initialization and cleanup logic
/// when objects are allocated from or returned to a pool.
///
/// # Examples
///
/// ```rust
/// use fastalloc::Poolable;
///
/// struct GameEntity {
///     position: (f32, f32),
///     velocity: (f32, f32),
///     health: i32,
/// }
///
/// impl Poolable for GameEntity {
///     fn on_acquire(&mut self) {
///         // Reset state when acquired from pool
///         self.position = (0.0, 0.0);
///         self.velocity = (0.0, 0.0);
///         self.health = 100;
///     }
///     
///     fn on_release(&mut self) {
///         // Cleanup before returning to pool
///         // (optional - could clear resources, etc.)
///     }
/// }
/// ```
pub trait Poolable {
    /// Called when an object is acquired from the pool.
    ///
    /// This is a good place to reset the object to a clean state.
    /// The default implementation does nothing.
    #[inline]
    fn on_acquire(&mut self) {}

    /// Called when an object is being returned to the pool.
    ///
    /// This is a good place to perform cleanup or release resources.
    /// The default implementation does nothing.
    #[inline]
    fn on_release(&mut self) {}
}

// Note: We don't provide a blanket implementation to allow users to implement Poolable
// for their types without conflicts. The trait has default methods so no implementation
// is required unless custom behavior is needed.

/// Internal trait for pool implementations.
///
/// This trait is not intended for direct use by library users.
#[doc(hidden)]
pub trait Pool<T> {
    /// Allocate an object from the pool with the given initial value.
    fn allocate(&self, value: T) -> Result<Self::Handle>
    where
        Self::Handle: Sized;

    /// The handle type returned by this pool.
    type Handle;
}

/// Trait for pools that support statistics collection.
#[cfg(feature = "stats")]
pub trait PoolStats {
    /// Get current statistics for this pool.
    fn statistics(&self) -> crate::stats::PoolStatistics;

    /// Reset statistics counters.
    fn reset_statistics(&self);
}

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

    #[test]
    fn poolable_default_impl() {
        struct TestType {
            value: i32,
        }

        impl Poolable for TestType {}

        let mut obj = TestType { value: 42 };

        // Should compile and do nothing (uses default impl)
        obj.on_acquire();
        obj.on_release();

        assert_eq!(obj.value, 42);
    }

    #[test]
    fn poolable_custom_impl() {
        struct CustomType {
            counter: i32,
        }

        impl Poolable for CustomType {
            fn on_acquire(&mut self) {
                self.counter = 0;
            }

            fn on_release(&mut self) {
                self.counter = -1;
            }
        }

        let mut obj = CustomType { counter: 100 };
        obj.on_acquire();
        assert_eq!(obj.counter, 0);

        obj.counter = 50;
        obj.on_release();
        assert_eq!(obj.counter, -1);
    }
}