]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 */ |