rand

Package rand.

Seeded, non-cryptographic random numbers for tests, simulations, sampling and retry jitter. One seed fixes the whole sequence on every platform, so a test that draws random inputs fails the same way on CI and on a laptop.

import "rand";

let r = rand.new(42);                  // same seed, same sequence
rand.below(r, 10);                     // int in [0, 10)
rand.between(r, 1, 6);                 // int in [1, 6], ends included
rand.unit(r);                          // float in [0, 1)
rand.chance(r, 0.25);                  // true about one time in four
rand.shuffle(r, xs);                   // reorders xs in place
rand.pick(r, xs) ?? fallback;          // none when xs is empty

// retry number `attempt` (0 first): uniform in [0, min(cap, base * 2^attempt)]
time.sleep(rand.backoff(r, attempt, 100000000, 30000000000));
rand.jitter(r, 60000000000, 0.1);      // 60s, give or take 10%

The generator is xoshiro256**, seeded through splitmix64. The tests pin its exact outputs against the authors' C code, so a seed means the same sequence in every slang release. Draws are unbiased: below and between redraw rather than take a plain modulo, and between covers the full int range. below(r, 0) and between(r, 5, 1) panic, like an index out of range, since there is no value to return. backoff uses full jitter, which spreads clients that failed together across the whole interval, and saturates at cap rather than overflowing. An Rng is not locked: give each spawned task its own with rand.fork(r), which stays reproducible from the parent's seed. rand.from_os() seeds from the OS when runs should differ. Neither is for secrets: tokens, keys and salts come from crypto.rand, because this generator's outputs reveal its state.

API#

gc struct Rng stdlib/rand/rand.sl:33#

A random number generator. Make one with new or from_os.

fn new(seed: int) -> Rng stdlib/rand/rand.sl:42#

A generator whose sequence is fixed by seed. Every int is a good seed, 0 and -1 included: splitmix64 spreads it over all 256 bits of state.

fn from_os() -> result[Rng, str] stdlib/rand/rand.sl:57#

A generator seeded from the operating system's CSPRNG, for when runs should differ (load generators, sampling in production). Its outputs are still predictable from earlier ones: this is not a source of secrets.

fn fork(r: Rng) -> Rng stdlib/rand/rand.sl:76#

A new generator seeded from r, for handing to a spawned task. Seeded parents give seeded children, so a whole run still replays from one seed. r advances by one step.

fn next_u64(r: Rng) -> u64 stdlib/rand/rand.sl:81#

The next 64 random bits.

fn below(r: Rng, n: int) -> int stdlib/rand/rand.sl:95#

An int in [0, n), each value equally likely. Panics if n is not positive: there is no int to return, as with an index out of range.

fn between(r: Rng, lo: int, hi: int) -> int stdlib/rand/rand.sl:104#

An int in [lo, hi], both ends included, each value equally likely. Panics if lo > hi. The full range, between(r, MIN, MAX), works.

fn unit(r: Rng) -> float stdlib/rand/rand.sl:119#

A float in the unit interval [0, 1): one of 2^53 evenly spaced values, so every float it returns is exact and 1.0 never appears.

fn chance(r: Rng, p: float) -> bool stdlib/rand/rand.sl:125#

True with probability p. p at or below 0 (or NaN) is never, p at or above 1 is always.

fn shuffle[T](r: Rng, xs: [T]) stdlib/rand/rand.sl:136#

Reorders xs in place, every order equally likely (Fisher-Yates).

fn pick[T](r: Rng, xs: [T]) -> opt[T] stdlib/rand/rand.sl:148#

One element of xs, each equally likely; none if xs is empty.

fn backoff(r: Rng, attempt: int, base: int, cap: int) -> int stdlib/rand/rand.sl:161#

How long to wait before retry number attempt (0 for the first retry): a uniform draw from [0, min(cap, base * 2^attempt)], the "full jitter" strategy. Spreading over the whole interval, not just its top, is what stops a crowd of clients that failed together from retrying together. Units are whatever base and cap use, nanoseconds for a duration. A negative attempt counts as 0; a base or cap at or below 0 gives 0.

fn jitter(r: Rng, d: int, frac: float) -> int stdlib/rand/rand.sl:185#

d scaled by a uniform factor in [1 - frac, 1 + frac]: jitter(r, d, 0.1) lands within 10% of d. frac is clamped to [0, 1] (NaN counts as 0), so the result is never negative. A d at or below 0 gives 0.