index.nct

//! Nocter standard library memory API.
//!
//! This file is the initial public surface for `std/mem`. The compiler must not
//! special-case the names Allocator, Layout, RawBuffer, alloc, free, or
//! page_allocator. Region-specific behavior is tracked through allocator
//! provenance from the `region ... using ...` language construct.
//!
//! Public allocation behavior belongs to allocator and buffer instance methods
//! plus global allocator sources. Allocation is not part of the compiler
//! primitive set; target-gated std internals provide the OS boundary behind
//! this common API.

see ./allocation.nct
see ./layout.nct
see ./raw_buffer.nct
see ./storage.nct

/// A validated storage size and alignment pair.
pub copy struct Layout

/// Owned raw storage shared by package-level collection implementations.
pub struct RawBuffer

/// An allocator whose failure policy terminates the program.
pub struct Allocator

/// The allocator selected for a lexical allocation region.
pub struct AllocationContext

/// An allocator that reports storage failure through `T!`.
pub struct TryAllocator

pub(/) noalloc func current_allocator(): Allocator

/// Adapts the active context for package-internal recoverable implementation cores.
pub(/) noalloc func current_try_allocator(): TryAllocator

/// Returns an ordinary page-backed allocator.
pub noalloc func page_allocator(): Allocator

/// Returns a recoverable page-backed allocator.
pub noalloc func page_try_allocator(): TryAllocator

pub(/) noalloc func empty_unbound_buffer(align: usize): RawBuffer

pub(/) noalloc func take_raw_buffer(buffer: &+RawBuffer): RawBuffer

construct Layout {
    /// Validates `size` and power-of-two `align` as one allocation request.
    pub noalloc func new(size: usize, align: usize): Self!
}

/// Allocates one validated layout with recoverable failure.
pub func try_alloc_layout(
    allocator: &+TryAllocator,
    requested: Layout,
): RawBuffer!

/// Allocates one validated layout under the allocator's terminating policy.
pub func alloc_layout(
    allocator: &+Allocator,
    requested: Layout,
): RawBuffer

pub(/) func try_grow_owned(buffer: &+RawBuffer, new_size: usize): void!

instance Allocator {
    /// Allocates `size` bytes with `align`, terminating on failure.
    pub method &+self.alloc(size: usize, align: usize): RawBuffer

    /// Grows owned storage while preserving its allocator affinity.
    pub method &+self.grow(buffer: &+RawBuffer, new_size: usize): void
}

instance TryAllocator {
    /// Allocates `size` bytes with recoverable layout or storage failure.
    pub method &+self.try_alloc(size: usize, align: usize): RawBuffer!

    /// Grows owned storage with recoverable failure and preserved allocator affinity.
    pub method &+self.try_grow(buffer: &+RawBuffer, new_size: usize): void!

}

instance RawBuffer {
    /// Exposes all owned bytes as a readonly view.
    pub noalloc method &self.bytes(): &[u8]

    /// Exposes all owned bytes as an exclusive view.
    pub noalloc method &+self.bytes_mut(): &+[u8]

    /// Returns a readonly prefix or a bounds error.
    pub noalloc method &self.prefix(len: usize): &[u8]!

    /// Returns an exclusive prefix or a bounds error.
    pub noalloc method &+self.prefix_mut(len: usize): &+[u8]!
}

instance Layout {
    /// Returns the validated byte size.
    pub noalloc method &self.size(): usize

    /// Returns the validated alignment.
    pub noalloc method &self.align(): usize
}