ceph/src/boost/boost/random/random_device.hpp

   1 /* boost random/random_device.hpp header file
   2  *
   3  * Copyright Jens Maurer 2000
   4  * Copyright Steven Watanabe 2010-2011
   5  * Distributed under the Boost Software License, Version 1.0. (See
   6  * accompanying file LICENSE_1_0.txt or copy at
   7  * http://www.boost.org/LICENSE_1_0.txt)
   8  *
   9  * $Id$
  10  *
  11  * Revision history
  12  *  2000-02-18  Portability fixes (thanks to Beman Dawes)
  13  */
  14
  15 //  See http://www.boost.org/libs/random for documentation.
  16
  17
  18 #ifndef BOOST_RANDOM_RANDOM_DEVICE_HPP
  19 #define BOOST_RANDOM_RANDOM_DEVICE_HPP
  20
  21 #include <string>
  22 #include <boost/config.hpp>
  23 #include <boost/noncopyable.hpp>
  24 #include <boost/random/detail/auto_link.hpp>
  25 #include <boost/system/config.hpp> // force autolink to find Boost.System
  26
  27 namespace boost {
  28 namespace random {
  29
  30 /**
  31  * Class \random_device models a \nondeterministic_random_number_generator.
  32  * It uses one or more implementation-defined stochastic processes to
  33  * generate a sequence of uniformly distributed non-deterministic random
  34  * numbers. For those environments where a non-deterministic random number
  35  * generator is not available, class random_device must not be implemented. See
  36  *
  37  *  @blockquote
  38  *  "Randomness Recommendations for Security", D. Eastlake, S. Crocker,
  39  *  J. Schiller, Network Working Group, RFC 1750, December 1994
  40  *  @endblockquote
  41  *
  42  * for further discussions.
  43  *
  44  * @xmlnote
  45  * Some operating systems abstract the computer hardware enough
  46  * to make it difficult to non-intrusively monitor stochastic processes.
  47  * However, several do provide a special device for exactly this purpose.
  48  * It seems to be impossible to emulate the functionality using Standard
  49  * C++ only, so users should be aware that this class may not be available
  50  * on all platforms.
  51  * @endxmlnote
  52  *
  53  * <b>Implementation Note for Linux</b>
  54  *
  55  * On the Linux operating system, token is interpreted as a filesystem
  56  * path. It is assumed that this path denotes an operating system
  57  * pseudo-device which generates a stream of non-deterministic random
  58  * numbers. The pseudo-device should never signal an error or end-of-file.
  59  * Otherwise, @c std::ios_base::failure is thrown. By default,
  60  * \random_device uses the /dev/urandom pseudo-device to retrieve
  61  * the random numbers. Another option would be to specify the /dev/random
  62  * pseudo-device, which blocks on reads if the entropy pool has no more
  63  * random bits available.
  64  *
  65  * <b>Implementation Note for Windows</b>
  66  *
  67  * On the Windows operating system, token is interpreted as the name
  68  * of a cryptographic service provider.  By default \random_device uses
  69  * MS_DEF_PROV.
  70  *
  71  * <b>Performance</b>
  72  *
  73  * The test program <a href="\boost/libs/random/performance/nondet_random_speed.cpp">
  74  * nondet_random_speed.cpp</a> measures the execution times of the
  75  * random_device.hpp implementation of the above algorithms in a tight
  76  * loop. The performance has been evaluated on an
  77  * Intel(R) Core(TM) i7 CPU Q 840 \@ 1.87GHz, 1867 Mhz with
  78  * Visual C++ 2010, Microsoft Windows 7 Professional and with gcc 4.4.5,
  79  * Ubuntu Linux 2.6.35-25-generic.
  80  *
  81  * <table cols="2">
  82  *   <tr><th>Platform</th><th>time per invocation [microseconds]</th></tr>
  83  *   <tr><td> Windows </td><td>2.9</td></tr>
  84  *   <tr><td> Linux </td><td>1.7</td></tr>
  85  * </table>
  86  *
  87  * The measurement error is estimated at +/- 1 usec.
  88  */
  89 class random_device : private noncopyable
  90 {
  91 public:
  92     typedef unsigned int result_type;
  93     BOOST_STATIC_CONSTANT(bool, has_fixed_range = false);
  94
  95     /** Returns the smallest value that the \random_device can produce. */
  96     static result_type min BOOST_PREVENT_MACRO_SUBSTITUTION () { return 0; }
  97     /** Returns the largest value that the \random_device can produce. */
  98     static result_type max BOOST_PREVENT_MACRO_SUBSTITUTION () { return ~0u; }
  99
 100     /** Constructs a @c random_device, optionally using the default device. */
 101     BOOST_RANDOM_DECL random_device();
 102     /**
 103      * Constructs a @c random_device, optionally using the given token as an
 104      * access specification (for example, a URL) to some implementation-defined
 105      * service for monitoring a stochastic process.
 106      */
 107     BOOST_RANDOM_DECL explicit random_device(const std::string& token);
 108
 109     BOOST_RANDOM_DECL ~random_device();
 110
 111     /**
 112      * Returns: An entropy estimate for the random numbers returned by
 113      * operator(), in the range min() to log2( max()+1). A deterministic
 114      * random number generator (e.g. a pseudo-random number engine)
 115      * has entropy 0.
 116      *
 117      * Throws: Nothing.
 118      */
 119     BOOST_RANDOM_DECL double entropy() const;
 120     /** Returns a random value in the range [min, max]. */
 121     BOOST_RANDOM_DECL unsigned int operator()();
 122
 123     /** Fills a range with random 32-bit values. */
 124     template<class Iter>
 125     void generate(Iter begin, Iter end)
 126     {
 127         for(; begin != end; ++begin) {
 128             *begin = (*this)();
 129         }
 130     }
 131
 132 private:
 133     class impl;
 134     impl * pimpl;
 135 };
 136
 137 } // namespace random
 138
 139 using random::random_device;
 140
 141 } // namespace boost
 142
 143 #endif /* BOOST_RANDOM_RANDOM_DEVICE_HPP */