2 * Copyright 2014 Facebook, Inc.
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
17 #ifndef FOLLY_BASE_RANDOM_H_
18 #define FOLLY_BASE_RANDOM_H_
21 #include "folly/ThreadLocal.h"
26 * Return a good seed for a random number generator.
28 uint32_t randomNumberSeed();
33 * A PRNG with one instance per thread. This PRNG uses a mersenne twister random
34 * number generator and is seeded from /dev/urandom. It should not be used for
35 * anything which requires security, only for statistical randomness.
37 * An instance of this class represents the current threads PRNG. This means
38 * copying an instance of this class across threads will result in corruption
40 * Most users will use the Random class which implicitly creates this class.
41 * However, if you are worried about performance, you can memoize the TLS
42 * lookups that get the per thread state by manually using this class:
44 * ThreadLocalPRNG rng = Random::threadLocalPRNG()
46 * Random::rand32(rng);
49 class ThreadLocalPRNG {
51 typedef uint32_t result_type;
53 uint32_t operator()() {
54 // Using a static method allows the compiler to avoid allocating stack space
56 return getImpl(local_);
59 static constexpr result_type min() {
60 return std::numeric_limits<result_type>::min();
62 static constexpr result_type max() {
63 return std::numeric_limits<result_type>::max();
68 local_ = localInstance.get();
75 class LocalInstancePRNG;
76 static LocalInstancePRNG* initLocal();
77 static folly::ThreadLocalPtr<ThreadLocalPRNG::LocalInstancePRNG>
80 static result_type getImpl(LocalInstancePRNG* local);
81 LocalInstancePRNG* local_;
90 using ValidRNG = typename std::enable_if<
91 std::is_unsigned<typename std::result_of<RNG&()>::type>::value,
97 * Returns a random uint32_t
99 template<class RNG = ThreadLocalPRNG>
100 static uint32_t rand32(ValidRNG<RNG> rrng = RNG()) {
101 uint32_t r = rrng.operator()();
106 * Returns a random uint32_t in [0, max). If max == 0, returns 0.
108 template<class RNG = ThreadLocalPRNG>
109 static uint32_t rand32(uint32_t max, ValidRNG<RNG> rng = RNG()) {
114 return std::uniform_int_distribution<uint32_t>(0, max - 1)(rng);
118 * Returns a random uint64_t
120 template<class RNG = ThreadLocalPRNG>
121 static uint64_t rand64(ValidRNG<RNG> rng = RNG()) {
122 return ((uint64_t) rng() << 32) | rng();
126 * Returns a random uint64_t in [0, max). If max == 0, returns 0.
128 template<class RNG = ThreadLocalPRNG>
129 static uint64_t rand64(uint64_t max, ValidRNG<RNG> rng = RNG()) {
134 return std::uniform_int_distribution<uint64_t>(0, max - 1)(rng);
138 * Returns true 1/n of the time. If n == 0, always returns false
140 template<class RNG = ThreadLocalPRNG>
141 static bool oneIn(uint32_t n, ValidRNG<RNG> rng = RNG()) {
146 return rand32(n, rng) == 0;
150 * Returns a double in [0, 1)
152 template<class RNG = ThreadLocalPRNG>
153 static double randDouble01(ValidRNG<RNG> rng = RNG()) {
154 return std::generate_canonical<double, std::numeric_limits<double>::digits>