From 0db27008fbd44253e428298cda58f6c8f56134f5 Mon Sep 17 00:00:00 2001 From: Abseil Team Date: Wed, 11 Jan 2023 15:06:02 -0800 Subject: Improve BitGen stability documentation Several problems with the previous documentation: * It said it's stable "within the same binary" but not stable "across multiple binary invocations". Those statements contradict each other. * It said "in the same binary will not produce the same sequence of variates within the same binary", which is repetitive since it says "in the same binary" twice. * The comments about the seed sequence were not all next to each other, they were split apart by a rand.req.urng comment. * It implied that process stability is all you get, whereas generally you also get changelist stability. * It said you can use a seed sequence with SharedBitGen, but you can't. * It said there is more info in std_seed_seq.h , but there isn't. PiperOrigin-RevId: 501389708 Change-Id: I5e3dbc3548cc051265b8d004191c23147eccecc3 --- absl/random/random.h | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'absl/random') diff --git a/absl/random/random.h b/absl/random/random.h index 71b63092..76720867 100644 --- a/absl/random/random.h +++ b/absl/random/random.h @@ -68,7 +68,7 @@ ABSL_NAMESPACE_BEGIN // // `absl::BitGen` may be constructed with an optional seed sequence type, // conforming to [rand.req.seed_seq], which will be mixed with additional -// non-deterministic data. +// non-deterministic data as detailed below. // // Example: // @@ -79,16 +79,16 @@ ABSL_NAMESPACE_BEGIN // // Generate an integer value in the closed interval [1,6] // int die_roll2 = absl::uniform_int_distribution(1, 6)(gen_with_seed); // +// Constructing two `absl::BitGen`s with the same seed sequence in the same +// process will produce the same sequence of variates, but need not do so across +// multiple processes even if they're executing the same binary. +// // `absl::BitGen` meets the requirements of the Uniform Random Bit Generator // (URBG) concept as per the C++17 standard [rand.req.urng] though differs // slightly with [rand.req.eng]. Like its standard library equivalents (e.g. // `std::mersenne_twister_engine`) `absl::BitGen` is not cryptographically // secure. // -// Constructing two `absl::BitGen`s with the same seed sequence in the same -// binary will produce the same sequence of variates within the same binary, but -// need not do so across multiple binary invocations. -// // This type has been optimized to perform better than Mersenne Twister // (https://en.wikipedia.org/wiki/Mersenne_Twister) and many other complex URBG // types on modern x86, ARM, and PPC architectures. @@ -147,7 +147,7 @@ using BitGen = random_internal::NonsecureURBGBase< // // `absl::InsecureBitGen` may be constructed with an optional seed sequence // type, conforming to [rand.req.seed_seq], which will be mixed with additional -// non-deterministic data. (See std_seed_seq.h for more information.) +// non-deterministic data, as detailed in the `absl::BitGen` comment. // // `absl::InsecureBitGen` meets the requirements of the Uniform Random Bit // Generator (URBG) concept as per the C++17 standard [rand.req.urng] though -- cgit v1.2.3