seed_sequences.h (4277B)
1 // Copyright 2017 The Abseil Authors. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 // 15 // ----------------------------------------------------------------------------- 16 // File: seed_sequences.h 17 // ----------------------------------------------------------------------------- 18 // 19 // This header contains utilities for creating and working with seed sequences 20 // conforming to [rand.req.seedseq]. In general, direct construction of seed 21 // sequences is discouraged, but use-cases for construction of identical bit 22 // generators (using the same seed sequence) may be helpful (e.g. replaying a 23 // simulation whose state is derived from variates of a bit generator). 24 25 #ifndef ABSL_RANDOM_SEED_SEQUENCES_H_ 26 #define ABSL_RANDOM_SEED_SEQUENCES_H_ 27 28 #include <iterator> 29 #include <random> 30 31 #include "absl/base/config.h" 32 #include "absl/base/nullability.h" 33 #include "absl/random/internal/salted_seed_seq.h" 34 #include "absl/random/internal/seed_material.h" 35 #include "absl/random/seed_gen_exception.h" 36 #include "absl/strings/string_view.h" 37 #include "absl/types/span.h" 38 39 namespace absl { 40 ABSL_NAMESPACE_BEGIN 41 42 // ----------------------------------------------------------------------------- 43 // absl::SeedSeq 44 // ----------------------------------------------------------------------------- 45 // 46 // `absl::SeedSeq` constructs a seed sequence according to [rand.req.seedseq] 47 // for use within bit generators. `absl::SeedSeq`, unlike `std::seed_seq` 48 // additionally salts the generated seeds with extra implementation-defined 49 // entropy. For that reason, you can use `absl::SeedSeq` in combination with 50 // standard library bit generators (e.g. `std::mt19937`) to introduce 51 // non-determinism in your seeds. 52 // 53 // Example: 54 // 55 // absl::SeedSeq my_seed_seq({a, b, c}); 56 // std::mt19937 my_bitgen(my_seed_seq); 57 // 58 using SeedSeq = random_internal::SaltedSeedSeq<std::seed_seq>; 59 60 // ----------------------------------------------------------------------------- 61 // absl::CreateSeedSeqFrom(bitgen*) 62 // ----------------------------------------------------------------------------- 63 // 64 // Constructs a seed sequence conforming to [rand.req.seedseq] using variates 65 // produced by a provided bit generator. 66 // 67 // You should generally avoid direct construction of seed sequences, but 68 // use-cases for reuse of a seed sequence to construct identical bit generators 69 // may be helpful (eg. replaying a simulation whose state is derived from bit 70 // generator values). 71 // 72 // If bitgen == nullptr, then behavior is undefined. 73 // 74 // Example: 75 // 76 // absl::BitGen my_bitgen; 77 // auto seed_seq = absl::CreateSeedSeqFrom(&my_bitgen); 78 // absl::BitGen new_engine(seed_seq); // derived from my_bitgen, but not 79 // // correlated. 80 // 81 template <typename URBG> 82 SeedSeq CreateSeedSeqFrom(URBG* urbg) { 83 SeedSeq::result_type seed_material[random_internal::kEntropyBlocksNeeded]; 84 85 if (!random_internal::ReadSeedMaterialFromURBG( 86 urbg, absl::MakeSpan(seed_material))) { 87 random_internal::ThrowSeedGenException(); 88 } 89 return SeedSeq(std::begin(seed_material), std::end(seed_material)); 90 } 91 92 // ----------------------------------------------------------------------------- 93 // absl::MakeSeedSeq() 94 // ----------------------------------------------------------------------------- 95 // 96 // Constructs an `absl::SeedSeq` salting the generated values using 97 // implementation-defined entropy. The returned sequence can be used to create 98 // equivalent bit generators correlated using this sequence. 99 // 100 // Example: 101 // 102 // auto my_seed_seq = absl::MakeSeedSeq(); 103 // std::mt19937 rng1(my_seed_seq); 104 // std::mt19937 rng2(my_seed_seq); 105 // EXPECT_EQ(rng1(), rng2()); 106 // 107 SeedSeq MakeSeedSeq(); 108 109 ABSL_NAMESPACE_END 110 } // namespace absl 111 112 #endif // ABSL_RANDOM_SEED_SEQUENCES_H_