PgAllocation

Namespace: Ankus

Assembly: Ankus.Runtime.dll

Owns one PostgreSQL palloc-family allocation and validates it before each managed access.

public sealed class PgAllocation : IDisposable

Operations follow the native allocator’s capabilities. Slab contexts require their fixed chunk size; Bump contexts support allocation and context cleanup but reject individual free and resize. Failed free or resize leaves the checked allocation live until its context reclaims it.

Inheritance: object

Implements: IDisposable

Properties

Alignment

Gets the original explicit alignment, or zero for PostgreSQL’s default alignment.

public nuint Alignment { get; }

Value: nuint

Context

Gets the owning context while the allocation remains live.

public PgMemoryContext Context { get; }

Value: PgMemoryContext

Length

Gets the allocation’s byte length.

public nuint Length { get; }

Value: nuint

Options

Gets the original initialization and native size policies, retained through resizing.

public PgAllocationOptions Options { get; }

Value: PgAllocationOptions

Methods

Borrow<T>(nuint)

Borrows a typed view whose bounds and shared allocation lifetime are checked on every access.

public PgNativeReference<T> Borrow<T>(nuint offset = 0) where T : unmanaged

Type parameters:

T

The unmanaged value type.

Parameters:

offset — nuint

The allocation byte offset of the complete value.

Returns: PgNativeReference<T>

A view without ownership or individual release rights.

Resizing is observed by existing views. Freeing, detaching, or resetting the allocation invalidates its views; no native pointer is cached by this checked borrow.

Clear(nuint, nuint)

Clears the allocation or a selected byte range.

public void Clear(nuint offset = 0, nuint length = 0)

Parameters:

offset — nuint

The allocation byte offset.

length — nuint

The number of bytes to clear, or zero to clear from the offset through the end.

Dispose()

Releases the allocation immediately. Context reset or deletion makes this operation a no-op.

public void Dispose()

Bump contexts reject individual release. A failed release preserves this handle and its storage; the native context still reclaims that storage on reset or deletion.

Read(Span<byte>, nuint)

Copies bytes from this allocation into managed memory.

public void Read(Span<byte> destination, nuint offset = 0)

Parameters:

destination — Span<byte>

The destination span.

offset — nuint

The allocation byte offset.

Read<T>(nuint)

Reads one unmanaged value from the allocation.

public T Read<T>(nuint offset = 0) where T : unmanaged

Type parameters:

T

The unmanaged value type.

Parameters:

offset — nuint

The allocation byte offset.

Returns: T

The copied value.

Reallocate(nuint, bool)

Resizes this allocation using PostgreSQL’s matching context allocator.

public void Reallocate(nuint length, bool zeroNewMemory = false)

Parameters:

length — nuint

The new byte length.

zeroNewMemory — bool

Whether to clear only the newly added bytes when growing.

The original huge size policy and alignment remain in effect. Shrinking is permitted even when zeroNewMemory is true; unlike PostgreSQL’s repalloc0, this clears only positive growth. Slab permits only its fixed size. Bump rejects resizing, preserving the original allocation.

TryReallocate(nuint, bool)

Attempts resizing without raising an out-of-memory error, preserving the old allocation on failure.

public bool TryReallocate(nuint length, bool zeroNewMemory = false)

Parameters:

length — nuint

The new byte length.

zeroNewMemory — bool

Whether to clear only the newly added bytes when growing.

Returns: bool

True after resizing, or false for allocator exhaustion; other native errors still throw.

Write(ReadOnlySpan<byte>, nuint)

Copies managed bytes into this allocation.

public void Write(ReadOnlySpan<byte> source, nuint offset = 0)

Parameters:

source — ReadOnlySpan<byte>

The source bytes.

offset — nuint

The allocation byte offset.

Write<T>(T, nuint)

Writes one unmanaged value to the allocation.

public void Write<T>(T value, nuint offset = 0) where T : unmanaged

Type parameters:

T

The unmanaged value type.

Parameters:

value — T

The value to copy.

offset — nuint

The allocation byte offset.