##### Docs

**C++ Devguide**- Quickstart (Bazel)
- Quickstart (CMake)
###### Programming Guides

- Abseil Fundamentals
- Containers
- Flags Library
- Hash Library
- Meta Library
- Numerics
- Options
- Random Library
- String Formatting
- Status
- String Utilities
- Synchronization
- Time Library
###### Platforms Guide

- Supported Platforms
- Compiler Flags
- Feature Check Macros
- Pre-compiled Macros
###### Tools Guide

- Clang-tidy Checks
- CMake Install Binaries
- Automated Upgrades
- Upgrade Tools
###### General Guides

- Atomic C++ Operations
**Python Devguide**

The Abseil Random library provides functions and utilities for generating
pseudorandom data. This library is designed to be used as a replacement for the
random number generators and distribution functions within the
`<random>`

library, while
maintaining compatibility with that library.

The Abseil Random library provides several advantages over `<random>`

:

**Improved algorithms**

The Abseil Random library provides improved pseudorandom algorithms, and allows us to adopt new algorithms as they become available. Random value generation is an area of active research, and today’s algorithms initialize more quickly, generate values faster, and produce sequences that are statistically more difficult to guess.**Easy construction of well-seeded generators**

Abseil’s bit generators require no constructor arguments to be seeded properly. Providing the initial state for a random value generator (ie.*“seeding”*) is a nontrivial task which often requires knowledge of the underlying bit-generation algorithm.**Concise sampling syntax**

Abseil’s Random library provides a more concise syntax than`<random>`

by representing distributions as functions rather than objects, while still decoupling bit generation from distribution sampling.

To get started, add the following `#include`

, and analogous dependency within
your build file.

```
#include "absl/random/random.h"
```

The Abseil Random library provides a variety of **distribution function
templates**, which produce randomly sampled values from particular
distributions. They obtain their randomness from a user-supplied **uniform
random bit generator** (URBG, or **bit generator** for short), which should be
treated as an opaque object unless you’re implementing a distribution function.
`absl::BitGen`

is the preferred bit generator for most use cases.

```
absl::BitGen bitgen;
size_t index = absl::Uniform(bitgen, 0u, elems.size());
double fraction = absl::Uniform(bitgen, 0, 1.0);
bool coin_flip = absl::Bernoulli(bitgen, 0.5);
```

Bit generators produce values with the function-call operator, but this interface should never be used directly in application code.

Properly sampling from a distribution can be surprisingly subtle; it requires knowledge of the underlying URBG algorithm, and the range of values that it produces. This range of values may or may not be the full space of values representable by the output data type. Getting these details wrong can result in biased sampling.

```
// Don't sample directly from a bit generator's output. If bitgen() produces
// values in the range [0,7], then this code will produce 1 and 2 twice as often
// as other values.
uint32_t die_roll = 1 + (bitgen() % 6);
// Instead, use a distribution function instead:
uint32_t die_roll = absl::Uniform(absl::IntervalClosed, gen, 1, 6);
```

Always use the Abseil Random library’s distribution functions instead.

Try to avoid continuously re-instantiating bit generators.

```
for (auto& elem : v_) {
absl::BitGen gen; // Newly instantiated for every element.
elem = absl::Uniform(gen, 0, 1.0);
}
```

It’s better to reuse generator instances, unless those generators will be called very infrequently.

```
class Server {
absl::BitGen bitgen_;
...
void Method() {
for (auto& elem : v_) {
elem = absl::Uniform(bitgen_, 0, 1.0);
}
}
};
```

`absl::Uniform()`

The most common use case for a random value library is also the most simple:
“Give me a number between *A* and *B*”.

```
int digit = absl::Uniform(gen, 0, 10); // Samples an integer from [0, 10)
```

or perhaps:

```
double less_than_1 = absl::Uniform(gen, 0, 1.0); // Samples from [0.0, 1.0)
```

or if we want to explicitly specify the desired numerical type, then perhaps:

```
// Casts arguments to the specified type, before sampling.
auto index = absl::Uniform<size_t>(gen, 0, v.size());
```

In the absence of an explicitly specified return type, the `absl::Uniform()`

function will use the more general of the two endpoints’ data types. Note that
if neither of these types can represent the other without loss of precision,
then the function call will not compile.

```
size_t index = absl::Uniform(gen, 0u, v.size()); // Both are unsigned types
auto index = absl::Uniform<size_t>(gen, 0, v.size()); // Also fine
```

```
size_t index = absl::Uniform(gen, 0, v.size()); // Error: int vs size_t
```

`absl::Uniform()`

You might sometimes find that sampling from the half-open distribution `[a, b)`

isn’t a natural fit for your application. For such cases, we allow endpoint
semantics to be explicitly specified, by providing one of the following
identifiers as the first function call argument:

```
absl::IntervalClosed // Sample from [a, b]
absl::IntervalOpen // Sample from (a, b)
absl::IntervalOpenClosed // Sample from (a, b]
absl::IntervalClosedOpen // Sample from [a, b) … (Default)
```

Some examples might include:

```
int die_roll = absl::Uniform(absl::IntervalClosed, gen, 1, 6);
double jitter = absl::Uniform(absl::IntervalOpen, gen, -0.25, 0.25);
```

Choose whichever endpoints and semantics most naturally fit to your use case.

One final note - Omitting the endpoints when sampling an unsigned integer provides a shorthand syntax for sampling from the entire type.

```
auto byte = absl::Uniform<uint8_t>(bitgen); // From [0, 255]
```

`BitGenRef`

: A Type-Erased URBG InterfaceAn instance of the `BitGenRef`

class can be thought of as a type-agnostic
“reference” to an
URBG
instance. Functions which accept an `absl::BitGenRef`

can be invoked using any
type of URBG, such as `absl::BitGen`

, `absl::InsecureBitGen`

, etc.

```
int TakesBitGenRef(absl::BitGenRef bitgen){
int v = absl::Uniform<int>(bitgen, 0, 1000);
}
```

`absl::BitGenRef`

has implicit conversion constructors from any `URBG&`

. A
`absl::BitGenRef`

does *not* copy or own the underlying URBG, to which it
points, and so the underlying URBG *must* outlive the `BitGenRef`

instance.

`MockingBitGen`

Importantly, `absl::BitGenRef`

allows mocking through the compatible
`absl::MockingBitGen`

type. When testing we might want to mock to provide
deterministic results. The `MockingBitGen`

provides such a mock for URBG
objects:

```
absl::MockingBitGen bitgen;
ON_CALL(absl::MockUniform<int>(), Call(bitgen, 1, 10000))
.WillByDefault(Return(20));
EXPECT_EQ(absl::Uniform<int>(bitgen, 1, 10000), 20);
EXPECT_CALL(absl::MockUniform<double>(), Call(bitgen, 0.0, 100.0))
.WillOnce(Return(5.0))
.WillOnce(Return(6.5));
EXPECT_EQ(absl::Uniform(bitgen, 0.0, 100.0), 5.0);
EXPECT_EQ(absl::Uniform(bitgen, 0.0, 100.0), 6.5);
```

`MockingBitGen`

has full support for Googletest matchers and actions.

`absl::BitGen`

acquires seed data from an an underlying entropy pool managed by
the Randen pseudorandom generator, initially
seeded from `/dev/urandom`

.

`absl::BitGen`

Over `absl::InsecureBitGen`

?The use of values produced by insecure bit generators in security-sensitive
contexts may introduce occasional (but dangerous) security issues. Although
`absl::BitGen`

is not suitable for cryptographic applications such as key
generation, it provides guarantees strong enough to be resilient to misuse.

Like the C++ standard library random engines, neither `absl::BitGen`

,
nor `absl::InsecureBitGen`

are thread safe.

Efficiently leveraging a bit generator shared between multiple threads can be
tricky and subtle. Use of locally-instantiated generators are preferred to
global application-owned bit generators protected by a `Mutex`

and shared across
multiple threads.

If your random sampling is happening on a hot path and you can afford a larger
memory footprint, then consider further reducing compute costs by using a
`thread_local absl::BitGen`

for the lifetime of your process (but note that it
must be inside a function). The usual subtleties of using `thread_local`

apply.

Yes - the distribution functions are compatible with any type conforming to the
`UniformRandomBitGenerator`

named requirement, as defined by C++11. This includes `std::`

types (e.g.
`std::minstd_rand0`

and `std::mt19937_64`

).

We recognize that there are use cases which inherently require universally
stable (ie. seed-stable) variate generation, but this represents a narrow class
of applications within Google. Such use cases require stability of both
generator algorithms and distribution algorithms; in some cases, they require
this stability across multiple platforms, as well. Providing this would
completely freeze our ability to update and improve the Abseil Random library
for the (much larger) class of applications which neither require nor benefit
from these constraints. We hope to revisit the question of how to provide for
these use cases in the future, but for now, we (by design) offer no API that
indefinitely provides the same Seed→Sequence_{Variate} mappings.

Most applications and unit tests do not need to explicitly depend on the sequence of variates generated by a given seed. If you believe that your binary is an exceptional use case, Abseil Random may not be the right library for you. That said, there is method to our “nondeterminstic-seed” madness, and it’s worth outlining.

Our experience has taught us that random value generators are the ultimate victims to Hyrum’s Law. The details of a generator’s implementation (i.e. the algorithm for generating values) is effectively equivalent to its interface (i.e. the values generated). There have been instances in which attempts to improve existing algorithms, such as the routine for sampling pseudorandom floating-point values, have been foiled by thousands of unit tests throughout Google which have become dependent on the sequences of values generated. Thus, the API and implementation for previous iterations of generators within Google is, in many respects, effectively frozen in place and cannot be improved.

In order to prevent this from befalling the Abseil Random library, we have
implemented a scheme whereby the seed material used to derive the initial state
of a generator (`absl::BitGen`

, `absl::InsecureBitGen`

) is mixed with
nondeterministic data. We refer to the conditions under which a generator
promises to produce the same variates from a fixed seed sequence, as the
*stability* of the generator.

In the course of our discussions, we found it useful to define the following categories of generator stability:

**Process Stability**: Given a fixed seed sequence*S*, and a collection of generator-instances*g*constructed within the same process execution, all generators_{1}(S), …, g_{n}(S)*g*will produce the same sequences of variates._{k}**Seed Stability**: Given a fixed seed sequence*S*, and a collection of generator instances*g*, all generators_{1}(S), …, g_{n}(S)*g*will produce the same sequence of variates, across all instances of any binaries._{k}

Our generator types provide **Process Stability**.
There is currently **no generator type in the Abseil Random library which
provides Seed Stability**. The motivation for this decision is as much
philosophical as it is practical: The legitimate use cases for an eternally
unchanging pseudorandom sequence are uncommon within Google.

The Abseil family of distribution classes and distribution functions (e.g.
`absl::Uniform()`

) should be considered to have
**Process Stability**.
We hope to provide support for seed-stable distributions in the future, but at
the moment, no API from the Abseil Random library guarantees this contract.