mirror of
https://github.com/boostorg/uuid.git
synced 2026-01-19 04:42:16 +00:00
Update documentation
This commit is contained in:
Peter Dimov
89
doc/uuid/basic_random_generator.adoc
Normal file
89
doc/uuid/basic_random_generator.adoc
Normal file
@@ -0,0 +1,89 @@
|
||||
[#basic_random_generator]
|
||||
== <boost/uuid/basic_random_generator.hpp>
|
||||
|
||||
:idprefix: basic_random_generator_
|
||||
|
||||
=== Synopsis
|
||||
|
||||
[source,c++]
|
||||
----
|
||||
namespace boost {
|
||||
namespace uuids {
|
||||
|
||||
template<class UniformRandomNumberGenerator>
|
||||
class basic_random_generator
|
||||
{
|
||||
private:
|
||||
|
||||
// exposition only
|
||||
UniformRandomNumberGenerator* p_;
|
||||
UniformRandomNumberGenerator g_;
|
||||
|
||||
public:
|
||||
|
||||
typedef uuid result_type;
|
||||
|
||||
basic_random_generator();
|
||||
explicit basic_random_generator(UniformRandomNumberGenerator& gen);
|
||||
explicit basic_random_generator(UniformRandomNumberGenerator* pGen);
|
||||
|
||||
result_type operator()();
|
||||
};
|
||||
|
||||
}} // namespace boost::uuids
|
||||
----
|
||||
|
||||
=== basic_random_generator
|
||||
|
||||
The class template `basic_random_generator` class generates a random number based UUID from a random number generator
|
||||
(one that conforms to the standard concept https://en.cppreference.com/w/cpp/named_req/UniformRandomBitGenerator[UniformRandomBitGenerator]
|
||||
or to the Boost.Random concept https://www.boost.org/doc/libs/1_85_0/doc/html/boost_random/reference.html#boost_random.reference.concepts.uniform_random_number_generator[UniformRandomNumberGenerator]).
|
||||
The default constructor will properly seed the random number generator if it requires the behavior for proper operation.
|
||||
Additional constructors allow you to provide your own `UniformRandomNumberGenerator` and you are responsible for properly seeding it if necessary.
|
||||
|
||||
```cpp
|
||||
basic_random_generator();
|
||||
```
|
||||
|
||||
Effects: :: Value-initializes `g_` and initializes `p_` to `nullptr`.
|
||||
If `g_.seed()` is a valid expression, calls `g_.seed( seed_seq );`
|
||||
to seed `g_`, where `seed_seq` is an object providing a
|
||||
`generate( first, last )` member function that fills the range
|
||||
`[first, last)` using entropy obtained from `std::random_device`.
|
||||
|
||||
NOTE: Random number generators conforming to the standard https://en.cppreference.com/w/cpp/named_req/RandomNumberEngine[RandomNumberEngine]
|
||||
or the Boost.Random concept https://www.boost.org/doc/libs/1_85_0/doc/html/boost_random/reference.html#boost_random.reference.concepts.pseudo_random_number_generator[PseudoRandomNumberGenerator]
|
||||
provide such `seed` member functions.
|
||||
|
||||
```cpp
|
||||
explicit basic_random_generator(UniformRandomNumberGenerator& gen);
|
||||
```
|
||||
|
||||
Effects: :: Value-initializes `g_` and initializes `p_` to `&gen`.
|
||||
|
||||
```cpp
|
||||
explicit basic_random_generator(UniformRandomNumberGenerator* pGen);
|
||||
```
|
||||
|
||||
Effects: :: Value-initializes `g_` and initializes `p_` to `pGen`.
|
||||
|
||||
```cpp
|
||||
result_type operator()();
|
||||
```
|
||||
|
||||
Effects: :: Generates and returns a version 4 UUID using random numbers
|
||||
obtained from `*p_`, if `p_ != nullptr`, and from `g_`, otherwise.
|
||||
|
||||
Example: ::
|
||||
+
|
||||
```cpp
|
||||
using namespace boost::uuids;
|
||||
|
||||
basic_random_generator<boost::mt19937> bulkgen;
|
||||
|
||||
for( int i = 0; i < 1000; ++i )
|
||||
{
|
||||
u = bulkgen();
|
||||
// do something with u
|
||||
}
|
||||
```
|
||||
@@ -6,89 +6,81 @@
|
||||
=== Synopsis
|
||||
|
||||
[source,c++]
|
||||
[subs=+quotes]
|
||||
----
|
||||
#include <boost/uuid/basic_random_generator.hpp>
|
||||
|
||||
namespace boost {
|
||||
namespace uuids {
|
||||
|
||||
class random_generator {
|
||||
public:
|
||||
typedef uuid result_type;
|
||||
result_type operator()();
|
||||
};
|
||||
// recommended for all uses
|
||||
|
||||
class random_generator
|
||||
{
|
||||
private:
|
||||
|
||||
// exposition only
|
||||
_unspecified-csprng-type_ g_;
|
||||
|
||||
template <typename UniformRandomNumberGenerator>
|
||||
class basic_random_generator {
|
||||
public:
|
||||
|
||||
typedef uuid result_type;
|
||||
|
||||
basic_random_generator();
|
||||
explicit basic_random_generator(UniformRandomNumberGenerator& gen);
|
||||
explicit basic_random_generator(UniformRandomNumberGenerator* pGen);
|
||||
random_generator();
|
||||
|
||||
result_type operator()();
|
||||
};
|
||||
|
||||
typedef basic_random_generator<boost::mt19937> random_generator_mt19937;
|
||||
// only provided for backward compatibility
|
||||
|
||||
typedef basic_random_generator<std::mt19937> random_generator_mt19937;
|
||||
typedef basic_random_generator<std::random_device> random_generator_pure;
|
||||
|
||||
}} // namespace boost::uuids
|
||||
----
|
||||
|
||||
=== Random Generator
|
||||
=== random_generator
|
||||
|
||||
`boost::uuids::random_generator` class generates uuids using operating system provided entropy. For the majority of use cases this should be sufficient, as this generator has very low startup overhead when compared to a generator with seeding requirements.
|
||||
The class `random_generator` generates UUIDs using a cryptographically strong random number generator, seeded with entropy from `std::random_device`.
|
||||
It's the recommended way to generate version 4 random-based UUIDs.
|
||||
|
||||
`boost::uuids::basic_random_generator` class generates a random number based uuid from a random number generator (one that conforms to the https://www.boost.org/libs/random/random-concepts.html#uniform-rng[UniformRandomNumberGenerator] concept). The default constructor will properly seed the random number generator if it requires the behavior for proper operation. Additional constructors allow you to provide your own `UniformRandomNumberGenerator` and you are responsible for properly seeding it if necessary.
|
||||
|
||||
`boost::uuids::random_generator_mt19937` is a type definition for: `boost::uuids::basic_random_generator<mt19937>` and is provided for convenience.
|
||||
|
||||
==== Platforms
|
||||
|
||||
The following platforms are supported and entropy selection logic explained:
|
||||
|
||||
* CloudABI
|
||||
* Unix
|
||||
** OpenBSD: use https://man.openbsd.org/arc4random.3[arc4random(3)]
|
||||
** Linux 3.17 or later: use http://man7.org/linux/man-pages/man2/getrandom.2.html[getrandom(2)]
|
||||
** Other systems with glibc 2.25 or later: use https://www.man7.org/linux/man-pages/man3/getentropy.3.html[getentropy(3)]
|
||||
** All other cases: use `/dev/urandom`
|
||||
* Windows (UWP Compatible): use BCrypt if available, otherwise use Wincrypt
|
||||
|
||||
==== Preprocessor Macros
|
||||
|
||||
* `BOOST_UUID_RANDOM_PROVIDER_FORCE_POSIX`: on Unix this will force the selection of `/dev/*random` over `getrandom(2)` or `getentropy(3)`.
|
||||
* `BOOST_UUID_RANDOM_PROVIDER_FORCE_WINCRYPT`: on Windows this will force the selection of Wincrypt over BCrypt.
|
||||
* `BOOST_UUID_RANDOM_PROVIDER_NO_LIB` (or `BOOST_ALL_NO_LIB`): disable Windows auto linking.
|
||||
* `BOOST_UUID_RANDOM_PROVIDER_GETRANDOM_DISABLE_LIBC_WRAPPER`: disable `getrandom(2)` on Linux even if it's available.
|
||||
|
||||
==== Performance
|
||||
|
||||
In most cases `random_generator` will be optimal. A benchmark can be found in the tests (`test_bench_random`) that will determine the cutoff point where `random_generator_mt19937` outperforms `random_generator` in wall time.
|
||||
|
||||
On Windows when using the wincrypt entropy provider, a measurable delay may occur the first time a `random_generator` is constructed within a running instance. This has been observed using `test_bench_random` and was so significant that the benchmark was changed to throw out the first loop of measurements.
|
||||
|
||||
==== Exceptions
|
||||
|
||||
The exception `boost::uuids::entropy_error` is thrown if there is an error getting entropy from the operating system.
|
||||
|
||||
==== Examples
|
||||
|
||||
```c++
|
||||
// Depending on the platform there may be a setup cost in
|
||||
// initializing the generator so plan to reuse it if you can.
|
||||
boost::uuids::random_generator gen;
|
||||
boost::uuids::uuid id = gen();
|
||||
std::cout << id << std::endl;
|
||||
boost::uuids::uuid id2 = gen();
|
||||
std::cout << id2 << std::endl;
|
||||
assert(id != id2);
|
||||
|
||||
// You can still use a PseudoRandomNumberGenerator to create
|
||||
// UUIDs, however this is not the preferred mechanism.
|
||||
boost::uuids::random_generator_mt19937 bulkgen;
|
||||
for (size_t i = 0; i < 1000; ++i)
|
||||
{
|
||||
boost::uuids::uuid u = bulkgen();
|
||||
// do something with u
|
||||
boost::ignore_unused(u);
|
||||
}
|
||||
```cpp
|
||||
random_generator();
|
||||
```
|
||||
|
||||
Effects: :: Initializes `g_`, an instance of a cryptographically strong
|
||||
random number generator, using entropy obtained from `std::random_device`.
|
||||
|
||||
```cpp
|
||||
result_type operator()();
|
||||
```
|
||||
|
||||
Effects: :: Generates and returns a version 4 UUID using random numbers
|
||||
obtained from `g_`.
|
||||
|
||||
Example: ::
|
||||
+
|
||||
```cpp
|
||||
using namespace boost::uuids;
|
||||
|
||||
random_generator gen;
|
||||
|
||||
uuid u1 = gen();
|
||||
std::cout << u1 << std::endl;
|
||||
|
||||
uuid u2 = gen();
|
||||
std::cout << u2 << std::endl;
|
||||
|
||||
assert( u1 != u2 );
|
||||
```
|
||||
|
||||
=== random_generator_mt19937
|
||||
|
||||
`random_generator_mt19937` is an alias for `basic_random_generator<std::mt19937>` and is only
|
||||
provided for backward compatibility.
|
||||
|
||||
=== random_generator_pure
|
||||
|
||||
`random_generator_pure` is an alias for `basic_random_generator<std::random_device>` and is only
|
||||
provided for backward compatibility.
|
||||
|
||||
|
||||
@@ -10,5 +10,6 @@ include::namespaces.adoc[]
|
||||
include::name_generator_sha1.adoc[]
|
||||
include::name_generator_md5.adoc[]
|
||||
include::name_generator.adoc[]
|
||||
include::basic_random_generator.adoc[]
|
||||
include::random_generator.adoc[]
|
||||
include::uuid_io.adoc[]
|
||||
|
||||
@@ -18,9 +18,7 @@
|
||||
namespace boost {
|
||||
namespace uuids {
|
||||
|
||||
//! generate a random-based uuid
|
||||
//! \param[in] UniformRandomNumberGenerator see Boost.Random documentation
|
||||
template <typename UniformRandomNumberGenerator>
|
||||
template<class UniformRandomNumberGenerator>
|
||||
class basic_random_generator
|
||||
{
|
||||
private:
|
||||
|
||||
@@ -14,21 +14,17 @@
|
||||
namespace boost {
|
||||
namespace uuids {
|
||||
|
||||
// only provided for compatibility with 1.85
|
||||
class random_generator_mt19937: public basic_random_generator<std::mt19937>
|
||||
{
|
||||
};
|
||||
|
||||
// only provided for compatibility with 1.85
|
||||
class random_generator_pure: public basic_random_generator<detail::random_device>
|
||||
{
|
||||
};
|
||||
|
||||
// the default random generator
|
||||
class random_generator: public basic_random_generator<detail::chacha20_12>
|
||||
{
|
||||
};
|
||||
|
||||
// only provided for compatibility with 1.85
|
||||
using random_generator_mt19937 = basic_random_generator<std::mt19937>;
|
||||
|
||||
// only provided for compatibility with 1.85
|
||||
using random_generator_pure = basic_random_generator<detail::random_device>;
|
||||
|
||||
}} // namespace boost::uuids
|
||||
|
||||
#endif // BOOST_UUID_RANDOM_GENERATOR_HPP_INCLUDED
|
||||
|
||||
Reference in New Issue
Block a user