ravel::VirtualRng Class Reference

The one source of randomness a Simulation may use. More...

#include <rng.hpp>

Public Types
using	Choice = std::uint64_t
	One recorded random draw. See the class comment.

Public Member Functions
	VirtualRng (std::uint64_t seed) noexcept
	A generator that draws fresh numbers from seed.
std::uint64_t	next_u64 ()
	Uniform over all 64-bit values.
std::uint64_t	next_below (std::uint64_t bound)
	Uniform in [0, bound), without modulo bias.
std::uint64_t	next_between (std::uint64_t low, std::uint64_t high)
	Uniform in [low, high], both included. low must not exceed high.
bool	chance (double probability)
	True with the given probability.
double	next_double ()
	Uniform in [0, 1). Built from next_u64(), so it shrinks toward 0.0.
const std::vector< Choice > &	choices () const noexcept
	Every choice made so far, in order: what was actually used, after clamping.

Static Public Member Functions
static VirtualRng	replaying (std::vector< Choice > choices)
	A generator that answers draws from choices instead of computing them.

Detailed Description

The one source of randomness a Simulation may use.

Every draw is a "choice": a bounded integer, where 0 is always the simplest outcome (the first option, no fault, the shortest delay). The generator records every choice it makes, and can later replay a recorded list instead of drawing fresh numbers. That is what lets a failing run be shrunk: edit the list, replay it, and see whether the bug survives.

Generating mode (the default): xoshiro256** seeded through splitmix64. Every operation is fixed-width integer arithmetic (or an exact conversion of it), so the same seed yields the same choices on every platform and compiler. std::mt19937 and the standard distributions are deliberately avoided; their output is not portable.

Replaying mode: choices come from the list. Each is clamped to the bound of the draw it answers, so any list is valid, and draws past the end of the list get 0.

NOT cryptographically secure. Never use it for keys, nonces or tokens.

Member Function Documentation

chance()

bool ravel::VirtualRng::chance

(

double

probability

)

True with the given probability.

Recorded as 1 (true) or 0 (false), so shrinking toward 0 removes the event. Probabilities of 0 or less, and 1 or more, are certain and neither draw nor record.

choices()

const std::vector< Choice > & ravel::VirtualRng::choices ( ) const

inlinenoexcept

Every choice made so far, in order: what was actually used, after clamping.

Replaying this list reproduces the run exactly.

next_below()

std::uint64_t ravel::VirtualRng::next_below

(

std::uint64_t

bound

)

Uniform in [0, bound), without modulo bias.

bound must be non-zero. A bound of 1 has only one outcome, so it neither draws nor records.

---

The documentation for this class was generated from the following file:

• include/ravel/rng.hpp