sptos-region

Memory region management for SPTOS Cognition Kernel

Overview

sptos-region implements the Region primitive from ADR-087. Regions are contiguous, capability-protected memory objects with one of three policies: Immutable, AppendOnly, or Slab. SPTOS does not implement demand paging -- all regions are physically backed at map time, eliminating page faults and swap complexity.

Key Features

• Three region policies — Immutable (set-once, deduplicatable), AppendOnly (write cursor, max_size), and Slab (fixed-size slots from free list)
• Slab allocator — Zero-fragmentation fixed-slot allocation with both standard and optimized implementations
• Optional mmap backing — Linux mmap support via the mmap feature flag
• Statistics collection — Track allocations, frees, and byte usage with the stats feature
• no_std compatible — Works without std when the default feature is disabled

Dependencies

Key internal dependencies:

• sptos-types — Kernel type definitions (RegionHandle, RegionPolicy, KernelError)

Usage

use sptos_region::{RegionManager, RegionConfig, SlabAllocator};
use sptos_types::{RegionPolicy, CapHandle};

let mut manager = RegionManager::new();
let handle = manager.create_region(
    RegionPolicy::slab(64, 1024),
    CapHandle::null(),
)?;

API Reference

Core Types

Type	Description
RegionManager	Central manager for creating and accessing regions
RegionConfig	Configuration for region creation
SlabAllocator	Fixed-size slot allocator with free-list management
SlabRegion	A region backed by slab allocation
AppendOnlyRegion	Write-once append region with cursor tracking
ImmutableRegion	Set-once region that cannot be modified after creation
OptimizedSlabAllocator	Performance-optimized slab allocator variant
RegionStats	Statistics counters (requires stats feature)