core.memory

ArenaAllocator : struct {
    data    : ^ArenaBlock = null
    first   : ^ArenaBlock = null
    current : ^ArenaBlock = null
    num_block : i32
    blocks : containers.ArrayList<^ArenaBlock>
}

ArenaBlock : struct {
    data    : RawPtr = null
    size    : i64 = 0
    offset  : i64 = 0
    next    : ^ArenaBlock = null

}

HeapAllocator : struct {}

PermanentAllocator : struct{
    first : ^PermanentBlock = null
    current : ^PermanentBlock = null
}

PermanentBlock : struct {
    data : RawPtr = null
    size : i64 = 0
    offset : i64 = 0
    next : ^PermanentBlock = null
}

PoolAllocator : struct {
    raw_backing : RawPtr = null
    slot_base   : RawPtr = null
    usage_map   : ^u8 = null
    free_list   : RawPtr = null
    block_size  : i64 = 0
    stride      : i64 = 0
    block_count : i64 = 0
    alignment   : i64 = 0
    free_count  : i64 = 0
}

ArenaAllocator : func( size_per_block : i64, num_block : i32 ) -> ^Allocator

Constructs an arena allocator from equally sized, preallocated blocks.

Parameters:
  size_per_block : i64 - size in bytes of each backing block. Must be positive.
  num_block      : i32 - number of backing blocks to allocate.

Returns:
  ^Allocator - allocator wrapper for the arena, or null when the size is invalid
               or allocation fails.

Notes:
  - A non-positive block count is normalized to one block.
  - Individual allocations are reclaimed by `clear` or `destroy`, not `free`.

DestroyArenaAllocator : func(alloc : ^^ArenaAllocator) -> MemoryStatus

Releases an arena allocator's block metadata and concrete policy object.

Parameters:
  alloc : ^^ArenaAllocator - pointer to the concrete arena policy pointer.

Returns:
  MemoryStatus - MemoryStatus.Ok when the policy was released;
                 MemoryStatus.Error when no policy was supplied.

Notes:
  - This low-level helper does not release the individual block buffers.
  - Prefer `Allocator.destroy()` while the arena still owns its block buffers.

arena_allocator_alloc : func(alloc_data : RawPtr, op : AllocatorOp, size : i64, alignment : i64, ptr : RawPtr ) -> [RawPtr, MemoryStatus]

Dispatches an allocator operation to a concrete arena policy.

Parameters:
  alloc_data : RawPtr      - concrete ArenaAllocator policy pointer.
  op         : AllocatorOp - operation to perform.
  size       : i64         - requested allocation size in bytes.
  alignment  : i64         - requested allocation alignment in bytes.
  ptr        : RawPtr      - allocation supplied to a free operation.

Returns:
  [RawPtr, MemoryStatus] - operation result pointer and status.

Notes:
  - This context-free function is suitable for use as `Allocator.alloc_fn`.

allocate_aligned : func(self : ^ArenaAllocator, size : i64, alignment : i64) -> [RawPtr, MemoryStatus]

Reserves aligned storage from the current or next available arena block.

Parameters:
  self      : ^ArenaAllocator - arena policy to allocate from.
  size      : i64             - number of bytes to reserve. Must be positive.
  alignment : i64             - requested power-of-two alignment in bytes.

Returns:
  [RawPtr, MemoryStatus] - aligned allocation and MemoryStatus.Ok on success;
                           MemoryStatus.Error for invalid arguments; or
                           MemoryStatus.OutOfMemory when no block can fit it.

Notes:
  - An alignment of zero requests one-byte alignment.
  - Existing allocations remain valid until the arena is cleared or destroyed.

allocate : func(self : ^ArenaAllocator, size : i64) -> [RawPtr, MemoryStatus]

Reserves storage from an arena using the default allocator alignment.

Parameters:
  self : ^ArenaAllocator - arena policy to allocate from.
  size : i64             - number of bytes to reserve. Must be positive.

Returns:
  [RawPtr, MemoryStatus] - allocation result and status.

free : func(self :  ^ArenaAllocator, ptr : RawPtr ) -> [RawPtr, MemoryStatus]

Accepts an individual arena allocation without reclaiming its storage.

Parameters:
  self : ^ArenaAllocator - arena policy associated with the allocation.
  ptr  : RawPtr         - allocation passed through unchanged.

Returns:
  [RawPtr, MemoryStatus] - the supplied pointer and MemoryStatus.Ok.

Notes:
  - Arena allocations are reclaimed together by `clear` or `destroy`.

clear : func(self :  ^ArenaAllocator)  -> [RawPtr, MemoryStatus]

Resets every arena block for reuse and selects the first block as current.

Parameters:
  self : ^ArenaAllocator - initialized arena policy to reset.

Returns:
  [RawPtr, MemoryStatus] - null and MemoryStatus.Ok.

Notes:
  - Existing pointers may be overwritten by subsequent allocations.

destroy : func(self : ^ArenaAllocator) -> [RawPtr, MemoryStatus]

Releases every arena block, its metadata, and the concrete policy object.

Parameters:
  self : ^ArenaAllocator - initialized arena policy to destroy.

Returns:
  [RawPtr, MemoryStatus] - null and MemoryStatus.Ok.

Notes:
  - The arena policy and all allocations from it are invalid after this call.

HeapAllocator : func() -> ^Allocator

Constructs an allocator backed by the process heap.

Parameters:
  none

Returns:
  ^Allocator - allocator wrapper whose allocations can be freed individually.

DestroyHeapAllocator : func(alloc : ^^HeapAllocator) -> MemoryStatus

Releases a concrete heap allocator policy object.

Parameters:
  alloc : ^^HeapAllocator - pointer to the concrete heap policy pointer.

Returns:
  MemoryStatus - MemoryStatus.Ok when the policy was released;
                 MemoryStatus.Error when no policy was supplied.

Notes:
  - Outstanding heap allocations must be freed separately.

allocate_aligned : func(self : ^HeapAllocator, size : i64, alignment : i64) -> [RawPtr, MemoryStatus]

Allocates storage from the process heap with a requested alignment.

Parameters:
  self      : ^HeapAllocator - heap policy to allocate from.
  size      : i64            - number of bytes to allocate. Must be positive.
  alignment : i64            - requested power-of-two alignment in bytes.

Returns:
  [RawPtr, MemoryStatus] - aligned allocation and MemoryStatus.Ok on success;
                           MemoryStatus.Error for invalid arguments; or
                           MemoryStatus.OutOfMemory when allocation fails.

Notes:
  - Alignments smaller than the default allocator alignment are promoted to it.
  - A private header retains the original `malloc` pointer for `free`.

allocate : func(self : ^HeapAllocator, size : i64) -> [RawPtr, MemoryStatus]

Allocates storage from the process heap using the default allocator alignment.

Parameters:
  self : ^HeapAllocator - heap policy to allocate from.
  size : i64            - number of bytes to allocate. Must be positive.

Returns:
  [RawPtr, MemoryStatus] - allocation result and status.

clear : func(self : ^HeapAllocator) -> [RawPtr, MemoryStatus]

Performs the allocator-wide clear operation without releasing heap allocations.

Parameters:
  self : ^HeapAllocator - heap policy to clear.

Returns:
  [RawPtr, MemoryStatus] - null and MemoryStatus.Ok.

Notes:
  - Heap allocations remain individually owned, so this operation is a no-op.

free : func(self : ^HeapAllocator, ptr : RawPtr) -> [RawPtr, MemoryStatus]

Releases an allocation produced by this heap allocator.

Parameters:
  self : ^HeapAllocator - heap policy associated with the allocation.
  ptr  : RawPtr        - non-null allocation to release.

Returns:
  [RawPtr, MemoryStatus] - null and MemoryStatus.Ok on success, or null and
                           MemoryStatus.Error for an invalid pointer.

destroy : func(self : ^HeapAllocator) -> [RawPtr, MemoryStatus]

Releases the concrete heap allocator policy object.

Parameters:
  self : ^HeapAllocator - heap policy to destroy.

Returns:
  [RawPtr, MemoryStatus] - null and MemoryStatus.Ok.

Notes:
  - Outstanding heap allocations must be freed separately before this call.

fill : func<T>(slice : []T, value : byte) -> []T

zero_fill : func<T>(slice : []T, value : T) -> []T

copy : func(dst : []u8, src : []u8) -> i64

copy_non_secure: func(dst : RawPtr, src : RawPtr, length : i64)

PermanentAllocator : func(buffer_size : i64 ) -> ^Allocator

Constructs a permanent allocator with an initial backing block.

Parameters:
  buffer_size : i64 - initial block size in bytes. Must be positive.

Returns:
  ^Allocator - allocator wrapper for the permanent policy, or null when the
               size is invalid or allocation fails.

Notes:
  - Additional, progressively larger blocks are appended as needed.
  - Individual allocations are reclaimed by `clear` or `destroy`, not `free`.

DestroyPermanentAllocator : func(alloc : ^^PermanentAllocator) -> MemoryStatus

Releases a concrete permanent allocator and all of its backing blocks.

Parameters:
  alloc : ^^PermanentAllocator - pointer to the concrete permanent policy pointer.

Returns:
  MemoryStatus - MemoryStatus.Ok when the policy was released;
                 MemoryStatus.Error when no policy was supplied.

Notes:
  - The concrete policy pointer is set to null after successful destruction.

permanent_allocator_alloc : func(alloc_data : RawPtr, op : AllocatorOp, size : i64, alignment : i64, ptr : RawPtr ) -> [RawPtr, MemoryStatus]

Dispatches an allocator operation to a concrete permanent policy.

Parameters:
  alloc_data : RawPtr      - concrete PermanentAllocator policy pointer.
  op         : AllocatorOp - operation to perform.
  size       : i64         - requested allocation size in bytes.
  alignment  : i64         - requested allocation alignment in bytes.
  ptr        : RawPtr      - allocation supplied to a free operation.

Returns:
  [RawPtr, MemoryStatus] - operation result pointer and status.

Notes:
  - This context-free function is suitable for use as `Allocator.alloc_fn`.

allocate_aligned : func(self : ^PermanentAllocator, size : i64, alignment : i64) -> [RawPtr, MemoryStatus]

Reserves aligned storage from stable, append-only backing blocks.

Parameters:
  self      : ^PermanentAllocator - permanent policy to allocate from.
  size      : i64                 - number of bytes to reserve. Must be positive.
  alignment : i64                 - requested power-of-two alignment in bytes.

Returns:
  [RawPtr, MemoryStatus] - aligned allocation and MemoryStatus.Ok on success;
                           MemoryStatus.Error for invalid arguments; or
                           MemoryStatus.OutOfMemory when growth fails.

Notes:
  - An alignment of zero requests one-byte alignment.
  - New blocks are appended when necessary; existing allocations never move.

allocate : func(self : ^PermanentAllocator, size : i64) -> [RawPtr, MemoryStatus]

Reserves storage from a permanent allocator using the default alignment.

Parameters:
  self : ^PermanentAllocator - permanent policy to allocate from.
  size : i64                 - number of bytes to reserve. Must be positive.

Returns:
  [RawPtr, MemoryStatus] - allocation result and status.

free : func(self : ^PermanentAllocator, ptr : RawPtr) -> [RawPtr, MemoryStatus]

Accepts an individual permanent allocation without reclaiming its storage.

Parameters:
  self : ^PermanentAllocator - permanent policy associated with the allocation.
  ptr  : RawPtr             - allocation accepted for API compatibility.

Returns:
  [RawPtr, MemoryStatus] - null and MemoryStatus.Ok.

Notes:
  - Permanent allocations are reclaimed together by `clear` or `destroy`.

clear : func(self : ^PermanentAllocator) -> [RawPtr, MemoryStatus]

Resets every backing block for reuse and selects the first block as current.

Parameters:
  self : ^PermanentAllocator - initialized permanent policy to reset.

Returns:
  [RawPtr, MemoryStatus] - null and MemoryStatus.Ok on success, or null and
                           MemoryStatus.Error for an invalid policy.

Notes:
  - Existing pointers may be overwritten by subsequent allocations.

destroy : func(self : ^PermanentAllocator) -> [RawPtr, MemoryStatus]

Releases every backing block and the concrete permanent policy object.

Parameters:
  self : ^PermanentAllocator - permanent policy to destroy.

Returns:
  [RawPtr, MemoryStatus] - null and MemoryStatus.Ok on success, or null and
                           MemoryStatus.Error for an invalid policy.

Notes:
  - The policy and all allocations from it are invalid after this call.

PoolAllocator : func(block_size : i64, block_count : i64) -> ^Allocator

Constructs a fixed-capacity pool for equally sized allocations using the
default allocator alignment.

Parameters:
  block_size  : i64 - maximum allocation size in bytes for one pool slot.
  block_count : i64 - number of slots owned by the pool.

Returns:
  ^Allocator - allocator wrapper for the pool, or null when an argument is
               invalid or allocation fails.

Notes:
  - Every successful allocation consumes exactly one slot.
  - Individual slots can be returned to the pool with `free`.

PoolAllocator : func(block_size : i64, block_count : i64, alignment : i64) -> ^Allocator

Constructs a fixed-capacity pool for equally sized allocations with an
explicit alignment.

Parameters:
  block_size  : i64 - maximum allocation size in bytes for one pool slot.
  block_count : i64 - number of slots owned by the pool.
  alignment   : i64 - requested power-of-two slot alignment in bytes.

Returns:
  ^Allocator - allocator wrapper for the pool, or null when an argument is
               invalid or allocation fails.

Notes:
  - Zero alignment follows allocator normalization and is promoted to the
    default allocator alignment.
  - Alignments smaller than the default allocator alignment are promoted to it.

DestroyPoolAllocator : func(alloc : ^^PoolAllocator) -> MemoryStatus

Releases a concrete pool allocator and all storage owned by it.

Parameters:
  alloc : ^^PoolAllocator - pointer to the concrete pool policy pointer.

Returns:
  MemoryStatus - MemoryStatus.Ok when the policy was released;
                 MemoryStatus.Error when no policy was supplied.

Notes:
  - The concrete policy pointer is set to null after successful destruction.
  - An Allocator wrapper that referenced the policy remains caller-owned.

allocate_aligned : func(self : ^PoolAllocator, size : i64, alignment : i64) -> [RawPtr, MemoryStatus]

Reserves one free pool slot with a requested alignment.

Parameters:
  self      : ^PoolAllocator - initialized pool policy to allocate from.
  size      : i64            - requested size in bytes.
  alignment : i64            - requested power-of-two alignment in bytes.

Returns:
  [RawPtr, MemoryStatus] - slot pointer and MemoryStatus.Ok on success;
                           MemoryStatus.Error for an invalid request; or
                           MemoryStatus.OutOfMemory when every slot is in use.

Notes:
  - The requested size cannot exceed the configured block size.
  - The requested alignment cannot exceed the pool's configured alignment.
  - Zero alignment follows allocator normalization and requests one-byte alignment.

allocate : func(self : ^PoolAllocator, size : i64) -> [RawPtr, MemoryStatus]

Reserves one free pool slot using the default allocator alignment.

Parameters:
  self : ^PoolAllocator - initialized pool policy to allocate from.
  size : i64            - requested size in bytes.

Returns:
  [RawPtr, MemoryStatus] - allocation result and status.

free : func(self : ^PoolAllocator, ptr : RawPtr) -> [RawPtr, MemoryStatus]

Returns one live slot to the pool.

Parameters:
  self : ^PoolAllocator - initialized pool policy that owns the slot.
  ptr  : RawPtr        - exact start address of a live pool slot.

Returns:
  [RawPtr, MemoryStatus] - null and MemoryStatus.Ok on success, or null and
                           MemoryStatus.Error for a null, foreign, interior,
                           or already-free pointer.

clear : func(self : ^PoolAllocator) -> [RawPtr, MemoryStatus]

Returns every slot to the pool and rebuilds its free list.

Parameters:
  self : ^PoolAllocator - initialized pool policy to reset.

Returns:
  [RawPtr, MemoryStatus] - null and MemoryStatus.Ok on success, or null and
                           MemoryStatus.Error for an invalid policy.

Notes:
  - Every outstanding allocation becomes invalid after this call.

destroy : func(self : ^PoolAllocator) -> [RawPtr, MemoryStatus]

Releases the pool's usage map, backing allocation, and concrete policy.

Parameters:
  self : ^PoolAllocator - initialized pool policy to destroy.

Returns:
  [RawPtr, MemoryStatus] - null and MemoryStatus.Ok on success, or null and
                           MemoryStatus.Error for an invalid policy.

Notes:
  - The Allocator wrapper remains caller-owned and must not be used afterward.