From 3b3525558d7725eed59b8ebea37e12db475ff339 Mon Sep 17 00:00:00 2001 From: Jeffrey Walton Date: Thu, 2 Apr 2020 08:29:45 -0400 Subject: Update documentation --- mersenne.h | 36 +++++++++++++++++++++--------------- 1 file changed, 21 insertions(+), 15 deletions(-) (limited to 'mersenne.h') diff --git a/mersenne.h b/mersenne.h index b49d4032..868777fa 100644 --- a/mersenne.h +++ b/mersenne.h @@ -3,7 +3,7 @@ /// \file mersenne.h /// \brief Class file for Mersenne Twister /// \warning MersenneTwister is suitable for Monte-Carlo simulations, where uniformaly distrubuted -/// numbers are required quickly. It should not be used for cryptographic purposes. +/// numbers are required quickly. It should not be used for cryptographic purposes. /// \since Crypto++ 5.6.3 #ifndef CRYPTOPP_MERSENNE_TWISTER_H #define CRYPTOPP_MERSENNE_TWISTER_H @@ -21,8 +21,10 @@ NAMESPACE_BEGIN(CryptoPP) /// \tparam F Multiplier constant /// \tparam S Initial seed /// \details Provides the MersenneTwister implementation. The class is a header-only implementation. +/// \details You should reseed the generator after a fork() to avoid multiple generators +/// with the same internal state. /// \warning MersenneTwister is suitable for simulations, where uniformaly distrubuted numbers are -/// required quickly. It should not be used for cryptographic purposes. +/// required quickly. It should not be used for cryptographic purposes. /// \sa MT19937, MT19937ar /// \since Crypto++ 5.6.3 template @@ -36,7 +38,7 @@ public: /// \brief Construct a Mersenne Twister /// \param seed 32-bit seed /// \details Defaults to template parameter S due to changing algorithm - /// parameters over time + /// parameters over time MersenneTwister(word32 seed = S) : m_seed(seed), m_idx(N) { Reset(seed); @@ -48,7 +50,7 @@ public: /// \param input the entropy to add to the generator /// \param length the size of the input buffer /// \details MersenneTwister uses the first 32-bits of input to reseed the - /// generator. If fewer bytes are provided, then the seed is padded with 0's. + /// generator. If fewer bytes are provided, then the seed is padded with 0's. void IncorporateEntropy(const byte *input, size_t length) { word32 temp = 0; @@ -63,9 +65,9 @@ public: /// \param output byte buffer /// \param size length of the buffer, in bytes /// \details Bytes are written to output in big endian order. If output length - /// is not a multiple of word32, then unused bytes are not accumulated for subsequent - /// calls to GenerateBlock. Rather, the unused tail bytes are discarded, and the - /// stream is continued at the next word32 boundary from the state array. + /// is not a multiple of word32, then unused bytes are not accumulated for subsequent + /// calls to GenerateBlock. Rather, the unused tail bytes are discarded, and the + /// stream is continued at the next word32 boundary from the state array. void GenerateBlock(byte *output, size_t size) { // Handle word32 size blocks @@ -102,7 +104,7 @@ public: /// \brief Generate a random 32-bit word in the range min to max, inclusive /// \returns random 32-bit word in the range min to max, inclusive /// \details If the 32-bit candidate is not within the range, then it is discarded - /// and a new candidate is used. + /// and a new candidate is used. word32 GenerateWord32(word32 min=0, word32 max=0xffffffffL) { const word32 range = max-min; @@ -122,9 +124,9 @@ public: /// \brief Generate and discard n bytes /// \param n the number of bytes to discard, rounded up to a word32 size /// \details If n is not a multiple of word32, then unused bytes are - /// not accumulated for subsequent calls to GenerateBlock. Rather, the unused - /// tail bytes are discarded, and the stream is continued at the next - /// word32 boundary from the state array. + /// not accumulated for subsequent calls to GenerateBlock. Rather, the unused + /// tail bytes are discarded, and the stream is continued at the next + /// word32 boundary from the state array. void DiscardBytes(size_t n) { for(size_t i=0; i < RoundUpToMultipleOf(n, 4U); i++) @@ -146,7 +148,7 @@ protected: /// \brief Returns the next 32-bit word from the state array /// \returns the next 32-bit word from the state array /// \details fetches the next word frm the state array, performs bit operations on - /// it, and then returns the value to the caller. + /// it, and then returns the value to the caller. word32 NextMersenneWord() { if (m_idx >= N) { Twist(); } @@ -201,8 +203,10 @@ private: /// \brief Original MT19937 generator provided in the ACM paper. /// \details MT19937 uses 4537 as default initial seed. +/// \details You should reseed the generator after a fork() to avoid multiple generators +/// with the same internal state. /// \sa MT19937ar, Mersenne twister: -/// a 623-dimensionally equidistributed uniform pseudo-random number generator +/// a 623-dimensionally equidistributed uniform pseudo-random number generator /// \since Crypto++ 5.6.3 #if CRYPTOPP_DOXYGEN_PROCESSING class MT19937 : public MersenneTwister<0x9908B0DF /*2567483615*/, 397, 624, 0x10DCD /*69069*/, 4537> {}; @@ -212,9 +216,11 @@ typedef MersenneTwister<0x9908B0DF /*2567483615*/, 397, 624, 0x10DCD /*69069*/, /// \brief Updated MT19937 generator adapted to provide an array for initialization. /// \details MT19937 uses 5489 as default initial seed. Use this generator when interoperating with C++11's -/// mt19937 class. +/// mt19937 class. +/// \details You should reseed the generator after a fork() to avoid multiple generators +/// with the same internal state. /// \sa MT19937, Mersenne Twister -/// with improved initialization +/// with improved initialization /// \since Crypto++ 5.6.3 #if CRYPTOPP_DOXYGEN_PROCESSING class MT19937ar : public MersenneTwister<0x9908B0DF /*2567483615*/, 397, 624, 0x6C078965 /*1812433253*/, 5489> {}; -- cgit v1.2.1