silk/random

Provider-replaceable pseudorandom words, booleans, bounded values, and byte filling.

When to use

Require Random when application code needs replaceable pseudorandom values. Use Xoshiro256StarStar with seeded when a reproducible sequence is required.

Details

nextU64 obtains one word from the active provider. nextBool, below, and fillBytes define one stable mapping from provider words to their results.

The Xoshiro256StarStar sequence is identical on all Silk execution engines. Its seed expansion uses SplitMix64, so every u64 seed is valid, including zero.

Gotchas

These APIs are deterministic and non-cryptographic. Do not use them for secrets, credentials, cryptographic keys, nonces, or security tokens.

Examples

Reproduce the first word from one seed

import silk.effect { Effect }

import silk.random as Random

pub fn main() -> i32 {
  let mut provider = Random.seeded(0)
  let first = run Random.nextU64()
    |> Effect.provideMut<Random.Random>(&mut provider)
  if first != 0x99ec5f36cb75f2b4 {
    return 0
  }
  return 42
}

Import as Random with import silk.random.

Public declarations: 7.

Random

pub service Random

An exclusive source of deterministic pseudorandom u64 words.

Details

A provider owns its state. Each nextU64 call advances only the provider supplied for the lexical Effect. Derived operations obtain all words through this service.

Gotchas

This service does not provide cryptographic randomness or operating-system entropy. Do not use its values for secrets, credentials, cryptographic keys, nonces, or security tokens.

Operation nextU64

effect fn nextU64() -> u64 ? &mut Random

Returns the next pseudorandom word and advances the active provider one time.

Gotchas

The result is deterministic provider output, not cryptographic randomness. Do not use it for secrets, credentials, cryptographic keys, nonces, or security tokens.

nextU64

pub effect fn nextU64() -> u64 ? &mut Random

Returns one word from the active Random provider.

Details

This operation advances the active provider exactly one time.

Gotchas

The result is deterministic pseudorandom data. Do not use it for secrets, credentials, cryptographic keys, nonces, or security tokens.

Xoshiro256StarStar

pub struct Xoshiro256StarStar

A deterministic xoshiro256** provider with four private u64 state words.

When to use

Use this provider when the same seed must produce the same sequence on every Silk engine.

Details

The provider uses the published xoshiro256** output and transition functions. It is not Copy, so one mutable provider has one advancing sequence.

Gotchas

This provider is non-cryptographic. Do not use it for secrets, credentials, cryptographic keys, nonces, or security tokens.

seeded

pub fn seeded(seed: u64) -> Xoshiro256StarStar

Creates a reproducible Xoshiro256StarStar provider from one u64 seed.

Details

Four successive SplitMix64 outputs initialize the provider state. Every u64 seed is valid, including zero. One seed always produces the same sequence on every Silk engine.

Gotchas

The resulting sequence is non-cryptographic. Do not use it for secrets, credentials, cryptographic keys, nonces, or security tokens.

Implementation Random for Xoshiro256StarStar

impl Random for Xoshiro256StarStar

Operation nextU64

nextU64 = Xoshiro256StarStar.xoshiroNext

nextBool

pub effect fn nextBool() -> bool ? &mut Random

Returns whether bit 63 of the next provider word is set.

Details

This operation consumes exactly one word. It does not cache the other bits.

Gotchas

The result is deterministic pseudorandom data. Do not use it for secrets, credentials, cryptographic keys, nonces, or security tokens.

below

pub effect fn below(upperExclusive: u64) -> Option<u64> ? &mut Random

Returns a pseudorandom value below upperExclusive, or None when the bound is zero.

Details

A zero bound consumes no provider word. A positive bound uses remainder rejection, so uniform provider words give each possible result the same probability.

Gotchas

Progress requires the provider to eventually return a word outside the rejection interval. The result is non-cryptographic and must not select secrets, keys, nonces, or security tokens.

fillBytes

pub effect fn fillBytes(output: &mut [u8]) -> () ? &mut Random

Fills output from consecutive provider words in least-significant-byte-first order.

Details

This operation allocates no storage. An empty slice consumes no word. A partial final group consumes one complete word and writes only the bytes that fit.

Gotchas

The bytes are deterministic and non-cryptographic. Do not use them for secrets, credentials, cryptographic keys, nonces, or security tokens.