random.cc File Reference

#include "kernel/random.h"
#include <atomic>
#include <cstdint>

Namespaces
namespace	ultra

Functions
std::size_t	ultra::random::ring (std::size_t base, std::size_t radius, std::size_t n)
engine_t &	ultra::random::engine ()
void	ultra::random::randomize ()

Detailed Description

Remarks

This file is part of ULTRA.

Copyright

Copyright (C) 2024 EOS di Manlio Morini.

License

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/

Function Documentation

engine()

engine_t & ultra::random::engine ( )

nodiscard

Every thread has its own generator initialised with a different seed.

randomize()

void ultra::random::randomize

(

)

Switches the random subsystem to an unpredictable state.

This function "re-bases" the process-wide seed counter so that random engines created after this call are typically seeded unpredictably.

Implementation notes / assumptions:

• engine_t::result_type is assumed to be an unsigned integer type at least 32 bits wide. This guarantees that cur + 1 is well-defined (wrap-around semantics) and provides a large seed space;
• the entropy used to re-base the counter is drawn from a small bounded interval, because randomize() is expected to be called only a few times and we do not need a huge entropy pool here;
• seed generation is thread-safe and lock-free: a CAS loop updates the atomic counter using relaxed memory ordering (no inter-thread ordering constraints are required).

Each thread owns its own thread-local random engine; therefore, only engines created after this call are affected. Existing engines are left unchanged.

This design allows deterministic and non-deterministic random behaviour to coexist within the same program, depending on when engines are initialised.

ring()

std::size_t ultra::random::ring ( std::size_t base, std::size_t radius, std::size_t n )

nodiscard

Returns a random number in a modular arithmetic system.

Parameters

[in]	base	a base number
[in]	radius	maximum distance from the base number
[in]	n	modulus

Returns

a random number in the [base - radius, base + radius] mod n interval