From 731afe80bcecbfb312984e04bfae6b803040ad4e Mon Sep 17 00:00:00 2001 From: Peter Dimov Date: Tue, 30 Apr 2024 20:58:03 +0300 Subject: [PATCH] Update documentation --- doc/uuid/basic_random_generator.adoc | 89 +++++++++++++ doc/uuid/random_generator.adoc | 126 ++++++++---------- doc/uuid/reference.adoc | 1 + include/boost/uuid/basic_random_generator.hpp | 4 +- include/boost/uuid/random_generator.hpp | 16 +-- 5 files changed, 156 insertions(+), 80 deletions(-) create mode 100644 doc/uuid/basic_random_generator.adoc diff --git a/doc/uuid/basic_random_generator.adoc b/doc/uuid/basic_random_generator.adoc new file mode 100644 index 0000000..3bfd1d7 --- /dev/null +++ b/doc/uuid/basic_random_generator.adoc @@ -0,0 +1,89 @@ +[#basic_random_generator] +== + +:idprefix: basic_random_generator_ + +=== Synopsis + +[source,c++] +---- +namespace boost { +namespace uuids { + +template +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 bulkgen; + +for( int i = 0; i < 1000; ++i ) +{ + u = bulkgen(); + // do something with u +} +``` diff --git a/doc/uuid/random_generator.adoc b/doc/uuid/random_generator.adoc index 575f293..900ce87 100644 --- a/doc/uuid/random_generator.adoc +++ b/doc/uuid/random_generator.adoc @@ -6,89 +6,81 @@ === Synopsis [source,c++] +[subs=+quotes] ---- +#include + 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 -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 random_generator_mt19937; +// only provided for backward compatibility + +typedef basic_random_generator random_generator_mt19937; +typedef basic_random_generator 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` 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` and is only +provided for backward compatibility. + +=== random_generator_pure + +`random_generator_pure` is an alias for `basic_random_generator` and is only +provided for backward compatibility. + diff --git a/doc/uuid/reference.adoc b/doc/uuid/reference.adoc index f922f95..5e668dd 100644 --- a/doc/uuid/reference.adoc +++ b/doc/uuid/reference.adoc @@ -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[] diff --git a/include/boost/uuid/basic_random_generator.hpp b/include/boost/uuid/basic_random_generator.hpp index b8737cd..c6ea5e2 100644 --- a/include/boost/uuid/basic_random_generator.hpp +++ b/include/boost/uuid/basic_random_generator.hpp @@ -18,9 +18,7 @@ namespace boost { namespace uuids { -//! generate a random-based uuid -//! \param[in] UniformRandomNumberGenerator see Boost.Random documentation -template +template class basic_random_generator { private: diff --git a/include/boost/uuid/random_generator.hpp b/include/boost/uuid/random_generator.hpp index f3942b1..6242867 100644 --- a/include/boost/uuid/random_generator.hpp +++ b/include/boost/uuid/random_generator.hpp @@ -14,21 +14,17 @@ namespace boost { namespace uuids { -// only provided for compatibility with 1.85 -class random_generator_mt19937: public basic_random_generator -{ -}; - -// only provided for compatibility with 1.85 -class random_generator_pure: public basic_random_generator -{ -}; - // the default random generator class random_generator: public basic_random_generator { }; +// only provided for compatibility with 1.85 +using random_generator_mt19937 = basic_random_generator; + +// only provided for compatibility with 1.85 +using random_generator_pure = basic_random_generator; + }} // namespace boost::uuids #endif // BOOST_UUID_RANDOM_GENERATOR_HPP_INCLUDED