silk/output

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc.

Owned output storage with separate uninitialized and initialized states.

When to use

Use this module when a foreign function writes one Copy result through a pointer.

Details

Each state owns one allocation. Initialization consumes the uninitialized state. Extraction consumes the initialized state and releases the allocation. An unused state releases its allocation without reading its contents.

Gotchas

An address does not initialize storage or keep it alive. Foreign code must not retain the address. Arbitrary foreign writes require an unsafe assertion that the complete value is valid.

Import as Uninitialized with import silk.output { Uninitialized }.

Public declarations: 2.

Uninitialized

pub struct Uninitialized<T>

Owns storage for one Copy value that has not been declared initialized.

Associated function Uninitialized.make

pub effect<'static> fn make<T>() -> silk/output.Uninitialized<T> ! OutOfMemoryError ? &mut Allocator

Allocates storage without constructing or reading a value.

Details

Allocation failure returns OutOfMemoryError without an output state.

Method Uninitialized.address

pub fn address<T, 'life1>(self: &'life1 mut Uninitialized<T>) -> *mut T

Returns the output address without reading or initializing the storage.

Gotchas

The address keeps no storage alive. Foreign code must finish its access before the owner is consumed or dropped.

Method Uninitialized.initialize

pub fn initialize<T>(self: Uninitialized<T>, value: T) -> silk/output.Initialized<T>

Writes a value and transfers the allocation into the initialized state.

Method Uninitialized.assumeInitialized

pub unsafe fn assumeInitialized<T>(self: Uninitialized<T>) -> silk/output.Initialized<T>

Transfers the allocation after the caller proves that foreign code initialized the complete value.

Gotchas

The storage must contain a valid T. Partial writes, untouched bytes that belong to the value, and invalid scalar or pointer representations do not satisfy this requirement.

Initialized

pub struct Initialized<T>

Owns storage for one initialized Copy value that can be extracted once.

Method Initialized.into

pub fn into<T>(self: Initialized<T>) -> T

Extracts the initialized value once and releases its allocation.