SecureRandom

Exposes OS-backed secure byte filling through safe portable slices. No seed, deterministic fallback, file path or application-global state exists. Output remains borrowed through native or asynchronous terminal completion. Disjoint buffers support concurrent calls; overlapping writes require external synchronization. Requests may fail even on a supported platform. Discard any partially initialized security input rather than using its failure prefix.

Module std.random

import std.random;

Public declaration contracts and authored examples. A page can document several related symbols. Implementation bodies are excluded.

SecureRandom

pub struct SecureRandom

Example

module example.secure_random;
from std.random import SecureRandom;
fn Main() -> i32 {
    var Empty: byte[0] = [];
    if SecureRandom.Fill(Empty) is .Err { Error = _ } { return 1; }
    var Bytes: byte[4] = [0_byte, 0_byte, 0_byte, 0_byte];
    switch SecureRandom.Fill(Bytes) {
        case .Ok => {} // Every byte is ready; no fixed content is expected.
        case .Err { Error = Error } => {
            if Error.Transferred > 4 { return 2; }
            return 3; // Discard this partial buffer; never substitute seeded bits.
        }
    }
    return 0;
}

SecureRandom.Fill

pub static fn Fill(Output: mut byte[]) -> Result<void, SecureRandomError>

Fills a live output slice from the selected OS entropy source. Output: Writable buffer borrowed only until return; empty is valid. Return: Complete fill or typed error with the exact initialized prefix. Warning: May block on entropy initialization. Performs no allocation.

SecureRandom.FillAsync

pub static async fn FillAsync(Output: mut byte[], mut Token: CancellationToken) -> Task<Result<void, SecureRandomError>>

Runs secure filling through the bounded blocking worker executor. Output: Writable range retained through task terminal cleanup. Token: Owned cancellation observation, inert by default. Return: Task with exact native result or zero-prefix admission failure. Cancellation prevents invocation when observed beforehand; it cannot abort an already-running native request or replace its committed result.

Example

module example.secure_random_async;
from std.random import SecureRandom;
from std.task import Task, CancellationSource;
async fn Main() -> Task<i32> {
    var Source = {
        // Scoped writable carriers end immediately after explicit payload transfer.
        var SourceCreation = CancellationSource.TryCreate();
        switch SourceCreation {
            case .Ok { Value = Value: mut CancellationSource& } => break move(Value);
            case .Err { Error = _ } => return 1;
        }
    };
    Source.RequestCancellation();
    var Bytes: byte[4] = [1_byte, 2_byte, 3_byte, 4_byte];
    switch await SecureRandom.FillAsync(Bytes, Source.Token) {
        case .Ok => return 2;
        case .Err { Error = Error } => {
            if !(Error.Reason is .Cancelled) || Error.Transferred != 0 { return 3; }
        }
    }
    if Bytes[0] != 1_byte || Bytes[3] != 4_byte { return 4; }
    switch await SecureRandom.FillAsync(Bytes) {
        case .Ok => {}
        case .Err { Error = _ } => return 5;
    }
    return 0;
}

SecureRandom.FillAsync

pub static fn FillAsync(Output: mut byte[]) -> Task<Result<void, SecureRandomError>>

Supplies the omitted arguments to FillAsync. Note: Defaults: Token = CancellationToken(). Output: Same input, ownership and lifetime contract as the full operation. Return: Exact full-operation result; no additional async frame is created.