Source src/silo:std.effects.random

1##! Random effect — entropy primitive.
2##!
3##! Sub-effect of `IO`. Today this file declares `+Random` and exposes
4##! the `random-gen-*` host primitives that back it; the typed
5##! `Random` trait, `.shuffle`, `.choice`, and friends arrive later.
6
7:use
8  :open core AnyInt AnyFloat Bool Bytes
9  :open effects.io IO
10:end
11
12# si[impl effect.random.decl+1]
13## Entropy effect. `.entropy` returns `n` random bytes from the host's
14## random source (MUST be cryptographically secure unless the host
15## documents otherwise).
16:effect(pub) Random IO
17  # si[impl effect.random.entropy]
18  ## Returns exactly `n` random bytes as a `Bytes`. `n` MUST be non-negative;
19  ## `0` returns an empty `Bytes`.
20  .entropy ( AnyInt -> Bytes )
21:end
22
23# si[impl effect.random.entropy]
24## Draws a uniformly random byte in `0..=255`, pushed as an `Int`. Host
25## primitive: backed by `rand::thread_rng()` (a thread-local CSPRNG seeded
26## from the OS entropy pool).
27@host
28:fn(pub) random-gen-u8 ( -> AnyInt ) :end
29
30# si[impl effect.random.entropy]
31## Draws a uniformly random 64-bit unsigned value, pushed as an `Int`.
32@host
33:fn(pub) random-gen-u64 ( -> AnyInt ) :end
34
35# si[impl effect.random.entropy]
36## Uniform 50/50 `Bool`.
37@host
38:fn(pub) random-gen-bool ( -> Bool ) :end
39
40# si[impl effect.random.entropy]
41## Draws a uniformly distributed `Float` in `[0.0, 1.0)` — matches the
42## `(Random AnyFloat)` impl sketch in `spec/effects/random.md`.
43@host
44:fn(pub) random-gen-f64 ( -> AnyFloat ) :end
45
46# si[impl effect.random.entropy]
47## Fills a `Bytes` of length `n` with random data. `n` MUST be
48## non-negative; `0` returns an empty `Bytes`.
49@host
50:fn(pub) random-gen-bytes ( AnyInt -> Bytes ) :end