use std::collections::VecDeque;
use std::ops::Deref;
use std::sync::{Arc, Mutex, Weak};
use std::time::Instant;
pub const SIZE_CLASSES: &[u64] = &[
1024, 4 * 1024, 16 * 1024, 64 * 1024, 256 * 1024, 1024 * 1024, 4 * 1024 * 1024, 16 * 1024 * 1024, ];
struct PoolEntry {
buffer: wgpu::Buffer,
size_class: u64,
last_used: Instant,
}
#[derive(Debug, Clone, Default)]
pub struct PoolStats {
pub total_allocated_bytes: u64,
pub available_bytes: u64,
pub available_count: usize,
pub in_use_count: usize,
pub total_allocations: u64,
pub total_acquisitions: u64,
pub hit_rate: f64,
}
struct BufferPoolInner {
available: [VecDeque<PoolEntry>; SIZE_CLASSES.len()],
in_use_count: usize,
total_allocated_bytes: u64,
max_bytes: u64,
total_allocations: u64,
total_acquisitions: u64,
}
impl BufferPoolInner {
fn new(max_bytes: u64) -> Self {
Self {
available: std::array::from_fn(|_| VecDeque::new()),
in_use_count: 0,
total_allocated_bytes: 0,
max_bytes,
total_allocations: 0,
total_acquisitions: 0,
}
}
fn size_class_index(size: u64) -> Option<usize> {
SIZE_CLASSES.iter().position(|&class| class >= size)
}
fn stats(&self) -> PoolStats {
let available_bytes: u64 = self
.available
.iter()
.enumerate()
.map(|(i, q)| SIZE_CLASSES[i] * (q.len() as u64))
.sum();
let available_count: usize = self.available.iter().map(|q| q.len()).sum();
let hit_rate = if self.total_acquisitions > 0 {
let misses = self.total_allocations as f64;
let total = self.total_acquisitions as f64;
(total - misses) / total
} else {
0.0
};
PoolStats {
total_allocated_bytes: self.total_allocated_bytes,
available_bytes,
available_count,
in_use_count: self.in_use_count,
total_allocations: self.total_allocations,
total_acquisitions: self.total_acquisitions,
hit_rate,
}
}
fn evict_until_under_budget(&mut self) -> u64 {
let mut evicted_bytes = 0u64;
while self.total_allocated_bytes > self.max_bytes {
let mut oldest_idx: Option<(usize, Instant)> = None;
for (class_idx, queue) in self.available.iter().enumerate() {
if let Some(entry) = queue.front() {
match oldest_idx {
None => oldest_idx = Some((class_idx, entry.last_used)),
Some((_, oldest_time)) if entry.last_used < oldest_time => {
oldest_idx = Some((class_idx, entry.last_used));
}
_ => {}
}
}
}
if let Some((class_idx, _)) = oldest_idx {
if let Some(entry) = self.available[class_idx].pop_front() {
let size = entry.size_class;
self.total_allocated_bytes = self.total_allocated_bytes.saturating_sub(size);
evicted_bytes += size;
drop(entry);
tracing::debug!(
size_class = size,
remaining_bytes = self.total_allocated_bytes,
"Evicted buffer from pool"
);
}
} else {
break;
}
}
evicted_bytes
}
fn return_buffer(&mut self, entry: PoolEntry) {
let class_idx = SIZE_CLASSES
.iter()
.position(|&c| c == entry.size_class)
.unwrap_or(0);
self.in_use_count = self.in_use_count.saturating_sub(1);
self.available[class_idx].push_back(entry);
tracing::trace!(
size_class = SIZE_CLASSES[class_idx],
in_use = self.in_use_count,
available = self.available[class_idx].len(),
"Returned buffer to pool"
);
}
}
#[derive(Clone)]
pub struct BufferPool {
inner: Arc<Mutex<BufferPoolInner>>,
}
impl BufferPool {
#[must_use]
pub fn new(max_bytes: u64) -> Self {
tracing::info!(max_mb = max_bytes / (1024 * 1024), "Created buffer pool");
Self {
inner: Arc::new(Mutex::new(BufferPoolInner::new(max_bytes))),
}
}
pub fn acquire(
&self,
device: &wgpu::Device,
min_size: u64,
usage: wgpu::BufferUsages,
label: &str,
) -> Option<PooledBuffer> {
let class_idx = BufferPoolInner::size_class_index(min_size)?;
let size_class = SIZE_CLASSES[class_idx];
let mut inner = self.inner.lock().ok()?;
inner.total_acquisitions += 1;
let entry = if let Some(mut entry) = inner.available[class_idx].pop_back() {
entry.last_used = Instant::now();
inner.in_use_count += 1;
tracing::trace!(
size_class = size_class,
label = label,
"Reused buffer from pool"
);
entry
} else {
inner.total_allocations += 1;
if inner.total_allocated_bytes + size_class > inner.max_bytes {
let evicted = inner.evict_until_under_budget();
if evicted > 0 {
tracing::debug!(evicted_bytes = evicted, "Evicted buffers to make room");
}
}
let buffer = device.create_buffer(&wgpu::BufferDescriptor {
label: Some(label),
size: size_class,
usage,
mapped_at_creation: false,
});
inner.total_allocated_bytes += size_class;
inner.in_use_count += 1;
tracing::debug!(
size_class = size_class,
label = label,
total_mb = inner.total_allocated_bytes / (1024 * 1024),
"Allocated new buffer"
);
PoolEntry {
buffer,
size_class,
last_used: Instant::now(),
}
};
drop(inner);
Some(PooledBuffer {
entry: Some(entry),
pool: Arc::downgrade(&self.inner),
actual_size: min_size,
})
}
#[must_use]
pub fn stats(&self) -> PoolStats {
self.inner
.lock()
.map(|inner| inner.stats())
.unwrap_or_default()
}
pub fn clear(&self) {
if let Ok(mut inner) = self.inner.lock() {
let mut cleared_bytes = 0u64;
for (idx, queue) in inner.available.iter_mut().enumerate() {
cleared_bytes += SIZE_CLASSES[idx] * (queue.len() as u64);
queue.clear();
}
inner.total_allocated_bytes = inner.total_allocated_bytes.saturating_sub(cleared_bytes);
tracing::info!(
cleared_mb = cleared_bytes / (1024 * 1024),
"Cleared buffer pool"
);
}
}
pub fn set_budget(&self, max_bytes: u64) {
if let Ok(mut inner) = self.inner.lock() {
inner.max_bytes = max_bytes;
tracing::info!(
max_mb = max_bytes / (1024 * 1024),
"Updated buffer pool budget"
);
}
}
pub fn log_usage(&self) {
if let Ok(inner) = self.inner.lock() {
let stats = inner.stats();
tracing::debug!(
total_mb = stats.total_allocated_bytes / (1024 * 1024),
available_mb = stats.available_bytes / (1024 * 1024),
in_use = stats.in_use_count,
available = stats.available_count,
hit_rate = format!("{:.1}%", stats.hit_rate * 100.0),
"Buffer pool usage"
);
}
}
}
pub struct PooledBuffer {
entry: Option<PoolEntry>,
pool: Weak<Mutex<BufferPoolInner>>,
actual_size: u64,
}
impl PooledBuffer {
#[inline]
#[must_use]
pub fn size_class(&self) -> u64 {
self.entry.as_ref().map(|e| e.size_class).unwrap_or(0)
}
#[inline]
#[must_use]
pub fn actual_size(&self) -> u64 {
self.actual_size
}
#[inline]
#[must_use]
pub fn buffer(&self) -> &wgpu::Buffer {
match self.entry.as_ref() {
Some(entry) => &entry.buffer,
None => {
unreachable!("PooledBuffer accessed after being returned to pool")
}
}
}
#[inline]
#[must_use]
pub fn try_buffer(&self) -> Option<&wgpu::Buffer> {
self.entry.as_ref().map(|e| &e.buffer)
}
}
impl Deref for PooledBuffer {
type Target = wgpu::Buffer;
fn deref(&self) -> &Self::Target {
self.buffer()
}
}
impl Drop for PooledBuffer {
fn drop(&mut self) {
if let Some(mut entry) = self.entry.take() {
entry.last_used = Instant::now();
if let Some(pool) = self.pool.upgrade() {
if let Ok(mut inner) = pool.lock() {
inner.return_buffer(entry);
return;
}
}
tracing::trace!(
size_class = entry.size_class,
"Buffer dropped (pool unavailable)"
);
}
}
}
impl std::fmt::Debug for PooledBuffer {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("PooledBuffer")
.field("size_class", &self.size_class())
.field("actual_size", &self.actual_size)
.finish()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_size_class_index() {
assert_eq!(BufferPoolInner::size_class_index(1), Some(0)); assert_eq!(BufferPoolInner::size_class_index(1024), Some(0)); assert_eq!(BufferPoolInner::size_class_index(1025), Some(1)); assert_eq!(BufferPoolInner::size_class_index(4096), Some(1)); assert_eq!(BufferPoolInner::size_class_index(4097), Some(2)); assert_eq!(BufferPoolInner::size_class_index(16 * 1024 * 1024), Some(7)); assert_eq!(
BufferPoolInner::size_class_index(16 * 1024 * 1024 + 1),
None
); }
#[test]
fn test_size_classes_are_increasing() {
for i in 1..SIZE_CLASSES.len() {
assert!(
SIZE_CLASSES[i] > SIZE_CLASSES[i - 1],
"Size classes must be strictly increasing"
);
}
}
#[test]
fn test_size_classes_are_powers_of_four() {
for i in 1..SIZE_CLASSES.len() {
assert_eq!(
SIZE_CLASSES[i],
SIZE_CLASSES[i - 1] * 4,
"Size class {} is not 4x the previous",
i
);
}
}
#[test]
fn test_pool_stats_initial() {
let pool = BufferPool::new(512 * 1024 * 1024);
let stats = pool.stats();
assert_eq!(stats.total_allocated_bytes, 0);
assert_eq!(stats.available_bytes, 0);
assert_eq!(stats.available_count, 0);
assert_eq!(stats.in_use_count, 0);
assert_eq!(stats.total_allocations, 0);
assert_eq!(stats.total_acquisitions, 0);
}
#[test]
fn test_pool_budget() {
let pool = BufferPool::new(100 * 1024 * 1024); let stats = pool.stats();
assert_eq!(stats.total_allocated_bytes, 0);
pool.set_budget(200 * 1024 * 1024); let stats = pool.stats();
assert_eq!(stats.total_allocated_bytes, 0);
}
#[test]
fn test_pool_clear() {
let pool = BufferPool::new(512 * 1024 * 1024);
pool.clear(); let stats = pool.stats();
assert_eq!(stats.available_count, 0);
}
#[test]
fn test_size_class_coverage() {
assert_eq!(SIZE_CLASSES[0], 1024); assert_eq!(SIZE_CLASSES[1], 4 * 1024); assert_eq!(SIZE_CLASSES[2], 16 * 1024); assert_eq!(SIZE_CLASSES[3], 64 * 1024); assert_eq!(SIZE_CLASSES[4], 256 * 1024); assert_eq!(SIZE_CLASSES[5], 1024 * 1024); assert_eq!(SIZE_CLASSES[6], 4 * 1024 * 1024); assert_eq!(SIZE_CLASSES[7], 16 * 1024 * 1024); }
#[test]
fn test_eviction_logic() {
let mut inner = BufferPoolInner::new(10 * 1024);
inner.total_allocated_bytes = 8 * 1024;
let evicted = inner.evict_until_under_budget();
assert_eq!(evicted, 0);
inner.total_allocated_bytes = 12 * 1024;
let evicted = inner.evict_until_under_budget();
assert_eq!(evicted, 0);
}
}