stack-arena 0.12.0

use std::alloc::Layout;

/// Error type for allocation failures.
///
/// This error is returned when an allocation operation fails, typically
/// due to insufficient memory or other resource constraints.
///
/// # Examples
///
/// ```
/// use stack_arena::{BufferArena, Allocator, AllocError};
/// use std::alloc::Layout;
///
/// // Create a BufferArena with a small fixed size
/// let mut arena = BufferArena::with_capacity(4096);
///
/// // First allocation succeeds
/// let layout1 = Layout::from_size_align(4096, 1).unwrap();
/// let ptr1 = unsafe { arena.allocate(layout1) }.unwrap();
///
/// // Second allocation fails due to insufficient space
/// let layout2 = Layout::from_size_align(1, 1).unwrap();
/// let result = unsafe { arena.allocate(layout2) };
/// assert!(result.is_err());
/// assert!(matches!(result, Err(AllocError::CapacityExceeded { requested: 1, remaining: 0 })));
/// ```
///
/// Note: Unlike `BufferArena`, the `StackArena` will automatically allocate new chunks
/// when the current chunk is full, so it rarely returns allocation errors.
///
/// # Implementation
///
/// This error implements the standard `Error` and `Display` traits,
/// allowing it to be used with error handling utilities like `Result`.
#[derive(Debug, PartialEq, Eq)]
pub enum AllocError {
    OutOfMemory,
    InvalidLayout(Layout),
    CapacityExceeded { requested: usize, remaining: usize },
}

impl std::fmt::Display for AllocError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            AllocError::OutOfMemory => write!(f, "out of memory"),
            AllocError::InvalidLayout(layout) => write!(f, "invalid layout: {layout:?}"),
            AllocError::CapacityExceeded {
                requested,
                remaining,
            } => write!(
                f,
                "capacity exceeded: requested={requested}, remaining={remaining}"
            ),
        }
    }
}

impl std::error::Error for AllocError {}