Struct BlockAllocator 

pub struct BlockAllocator { /* private fields */ }

Block allocator with extent-based free-list tracking.

Manages space within a .luci file as fixed 256 KB blocks. The header occupies the first 4 KB of the file; blocks start immediately after. Allocation searches the free list first (first-fit), then extends the file if no suitable free extent exists. Deallocation returns extents to the free list and coalesces adjacent entries.

See [[architecture-storage-format#Block Allocator]].

Implementations

impl BlockAllocator

pub fn new() -> Self

Create an allocator for a new, empty file.

A fresh file has only the 4 KB header — no data blocks yet. All allocations extend the file.

pub fn from_state(total_blocks: u64, free_list: Vec<Extent>) -> Self

Reconstruct an allocator from persisted state.

Called during recovery: the metadata root block stores total_blocks and the serialized free list.

pub fn allocate(&mut self, count: u32) -> Result<Extent>

Allocate count contiguous blocks.

Strategy: first-fit scan of the free list. If no free extent is large enough, extends the file by appending blocks at the end.

Errors

Returns LuciError::InvalidQuery if count is zero.

pub fn free(&mut self, extent: Extent)

Return an extent to the free list.

The freed blocks become available for future allocations. Adjacent free extents are coalesced to reduce fragmentation.

Panics

Debug-asserts that the extent falls within [0, total_blocks) and does not overlap any existing free extent.

pub fn total_blocks(&self) -> u64

Total number of data blocks the file spans (excludes the header).

pub fn free_block_count(&self) -> u64

Total number of free (reusable) blocks.

pub fn free_list(&self) -> &[Extent]

Snapshot of the current free list (for persistence in metadata root).

Trait Implementations

impl Debug for BlockAllocator

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.