legacy-libs/grpc-cloned/deps/grpc/third_party/abseil-cpp/absl/random/seed_sequences.h

   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/random/internal/salted_seed_seq.h"
  32 #include "absl/random/internal/seed_material.h"
  33 #include "absl/random/seed_gen_exception.h"
  34 #include "absl/types/span.h"
  35
  36 namespace absl {
  37
  38 // -----------------------------------------------------------------------------
  39 // absl::SeedSeq
  40 // -----------------------------------------------------------------------------
  41 //
  42 // `absl::SeedSeq` constructs a seed sequence according to [rand.req.seedseq]
  43 // for use within bit generators. `absl::SeedSeq`, unlike `std::seed_seq`
  44 // additionally salts the generated seeds with extra implementation-defined
  45 // entropy. For that reason, you can use `absl::SeedSeq` in combination with
  46 // standard library bit generators (e.g. `std::mt19937`) to introduce
  47 // non-determinism in your seeds.
  48 //
  49 // Example:
  50 //
  51 //   absl::SeedSeq my_seed_seq({a, b, c});
  52 //   std::mt19937 my_bitgen(my_seed_seq);
  53 //
  54 using SeedSeq = random_internal::SaltedSeedSeq<std::seed_seq>;
  55
  56 // -----------------------------------------------------------------------------
  57 // absl::CreateSeedSeqFrom(bitgen*)
  58 // -----------------------------------------------------------------------------
  59 //
  60 // Constructs a seed sequence conforming to [rand.req.seedseq] using variates
  61 // produced by a provided bit generator.
  62 //
  63 // You should generally avoid direct construction of seed sequences, but
  64 // use-cases for reuse of a seed sequence to construct identical bit generators
  65 // may be helpful (eg. replaying a simulation whose state is derived from bit
  66 // generator values).
  67 //
  68 // If bitgen == nullptr, then behavior is undefined.
  69 //
  70 // Example:
  71 //
  72 //   absl::BitGen my_bitgen;
  73 //   auto seed_seq = absl::CreateSeedSeqFrom(&my_bitgen);
  74 //   absl::BitGen new_engine(seed_seq); // derived from my_bitgen, but not
  75 //                                      // correlated.
  76 //
  77 template <typename URBG>
  78 SeedSeq CreateSeedSeqFrom(URBG* urbg) {
  79   SeedSeq::result_type
  80       seed_material[random_internal::kEntropyBlocksNeeded];
  81
  82   if (!random_internal::ReadSeedMaterialFromURBG(
  83           urbg, absl::MakeSpan(seed_material))) {
  84     random_internal::ThrowSeedGenException();
  85   }
  86   return SeedSeq(std::begin(seed_material), std::end(seed_material));
  87 }
  88
  89 // -----------------------------------------------------------------------------
  90 // absl::MakeSeedSeq()
  91 // -----------------------------------------------------------------------------
  92 //
  93 // Constructs an `absl::SeedSeq` salting the generated values using
  94 // implementation-defined entropy. The returned sequence can be used to create
  95 // equivalent bit generators correlated using this sequence.
  96 //
  97 // Example:
  98 //
  99 //   auto my_seed_seq = absl::MakeSeedSeq();
 100 //   std::mt19937 rng1(my_seed_seq);
 101 //   std::mt19937 rng2(my_seed_seq);
 102 //   EXPECT_EQ(rng1(), rng2());
 103 //
 104 SeedSeq MakeSeedSeq();
 105
 106 }  // namespace absl
 107
 108 #endif  // ABSL_RANDOM_SEED_SEQUENCES_H_