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