zeropool 0.4.0

High-performance buffer pool with constant-time allocation, thread-safe operations, and 5x speedup over bytes crate
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

use std::thread;

use crate::pool::{BufferPool, PoolState};
use crate::size_class::ClassTable;

/// Default minimum buffer size (4KB) — smallest poolable size class.
const DEFAULT_MIN_BUFFER_SIZE: usize = 4 * 1024;

/// Calculate optimal TLS cache size per size class based on CPU count.
const fn default_tls_cache_size(num_cpus: usize) -> usize {
    match num_cpus {
        0..=2 => 2,
        3..=4 => 4,
        5..=8 => 6,
        _ => 8,
    }
}

/// Calculate max buffers per size class based on system parallelism.
const fn default_max_buffers_per_class(num_cpus: usize) -> usize {
    const BASE: usize = 32;
    let scaling = match num_cpus {
        0..16 => 1,
        16..32 => 2,
        32..64 => 3,
        _ => 4,
    };
    BASE * scaling
}

/// Calculate default batch transfer size based on TLS cache size.
const fn default_batch_size(tls_cache_size: usize) -> usize {
    let half = tls_cache_size / 2;
    if half < 2 { 2 } else { half }
}

/// Builder for configuring a [`BufferPool`].
///
/// # Example
/// ```
/// use zeropool::BufferPool;
///
/// let pool = BufferPool::builder()
///     .min_buffer_size(4096)
///     .tls_cache_size(4)
///     .build();
/// ```
#[derive(Debug, Clone, Default)]
pub struct Builder {
    tls_cache_size: Option<usize>,
    max_buffers_per_class: Option<usize>,
    min_buffer_size: Option<usize>,
    pinned_memory: Option<bool>,
    batch_size: Option<usize>,
}

impl Builder {
    /// Set the minimum buffer size to keep in the pool.
    ///
    /// Buffers smaller than this are discarded when returned.
    /// Default: 4KB
    pub fn min_buffer_size(mut self, size: usize) -> Self {
        self.min_buffer_size = Some(size);
        self
    }

    /// Set the number of buffers kept in thread-local cache per size class.
    ///
    /// Higher values reduce shared pool access but increase per-thread memory.
    /// Default: 2–8 based on CPU count
    pub fn tls_cache_size(mut self, size: usize) -> Self {
        self.tls_cache_size = Some(size);
        self
    }

    /// Set the maximum number of buffers per size class in the shared pool.
    ///
    /// Controls how many buffers of each size the shared pool retains.
    /// Default: 32–128 based on CPU count
    pub fn max_buffers_per_class(mut self, count: usize) -> Self {
        self.max_buffers_per_class = Some(count);
        self
    }

    /// Enable pinned memory (mlock) for pooled buffers.
    ///
    /// Locks buffers in RAM to prevent swapping. Useful for latency-critical
    /// or security-sensitive applications. Falls back gracefully if pinning fails.
    /// Default: false
    pub fn pinned_memory(mut self, enabled: bool) -> Self {
        self.pinned_memory = Some(enabled);
        self
    }

    /// Set the batch size for TLS ↔ shared pool transfers.
    ///
    /// When a thread-local cache misses, this many buffers are moved at once
    /// from the shared pool (magazine-style). Larger values amortize access
    /// cost but increase per-transfer latency.
    /// Default: half of TLS cache size (min 2)
    pub fn batch_size(mut self, size: usize) -> Self {
        self.batch_size = Some(size);
        self
    }

    /// Build the [`BufferPool`] with the configured settings.
    ///
    /// Any settings not explicitly set use system-aware defaults.
    ///
    /// # Panics
    ///
    /// Panics if `tls_cache_size` is 0 or `max_buffers_per_class` is 0.
    pub fn build(self) -> BufferPool {
        let num_cpus = thread::available_parallelism().map_or(4, std::num::NonZero::get);

        let tls_cache_size =
            self.tls_cache_size.unwrap_or_else(|| default_tls_cache_size(num_cpus));

        let max_buffers_per_class = self
            .max_buffers_per_class
            .unwrap_or_else(|| default_max_buffers_per_class(num_cpus));

        assert!(tls_cache_size > 0, "tls_cache_size must be > 0");
        assert!(max_buffers_per_class > 0, "max_buffers_per_class must be > 0");

        let batch_size = self.batch_size.unwrap_or_else(|| default_batch_size(tls_cache_size));

        BufferPool::from_state(PoolState {
            id: BufferPool::next_id(),
            table: ClassTable::new(max_buffers_per_class),
            tls_cache_size,
            min_buffer_size: self.min_buffer_size.unwrap_or(DEFAULT_MIN_BUFFER_SIZE),
            pinned_memory: self.pinned_memory.unwrap_or(false),
            batch_size,
        })
    }
}