| 1 | <html> |
|---|
| 2 | |
|---|
| 3 | <head> |
|---|
| 4 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
|---|
| 5 | |
|---|
| 6 | <title>Boost RNG Library - Non-Deterministic Random Number Generators</title> |
|---|
| 7 | </head> |
|---|
| 8 | |
|---|
| 9 | <body bgcolor="#FFFFFF" text="#000000"> |
|---|
| 10 | |
|---|
| 11 | <h1><img src="../../boost.png" alt="boost.png (6897 bytes)" |
|---|
| 12 | align="center" width="277" height="86">Header |
|---|
| 13 | <a href="../../boost/nondet_random.hpp"><boost/nondet_random.hpp></a></h1> |
|---|
| 14 | |
|---|
| 15 | <ul> |
|---|
| 16 | <li><a href="#synopsis">Synopsis</a> |
|---|
| 17 | <li><a href="#random_device">Class <code>random_device</code></a> |
|---|
| 18 | <li><a href="#performance">Performance</a> |
|---|
| 19 | </ul> |
|---|
| 20 | |
|---|
| 21 | <h2><a name="synopsis">Header</a><code><boost/nondet_random.hpp></code> |
|---|
| 22 | Synopsis</h2> |
|---|
| 23 | |
|---|
| 24 | <pre> |
|---|
| 25 | namespace boost { |
|---|
| 26 | class random_device; |
|---|
| 27 | } // namespace boost |
|---|
| 28 | </pre> |
|---|
| 29 | |
|---|
| 30 | |
|---|
| 31 | <h2><a name="random_device">Class <code>random_device</code></a></h2> |
|---|
| 32 | |
|---|
| 33 | <h3>Synopsis</h3> |
|---|
| 34 | |
|---|
| 35 | <pre> |
|---|
| 36 | class random_device : noncopyable |
|---|
| 37 | { |
|---|
| 38 | public: |
|---|
| 39 | typedef unsigned int result_type; |
|---|
| 40 | static const bool has_fixed_range = true; |
|---|
| 41 | static const result_type min_value = /* implementation defined */; |
|---|
| 42 | static const result_type max_value = /* implementation defined */; |
|---|
| 43 | result_type min() const; |
|---|
| 44 | result_type max() const; |
|---|
| 45 | explicit random_device(const std::string& token = default_token); |
|---|
| 46 | ~random_device(); |
|---|
| 47 | double entropy() const; |
|---|
| 48 | unsigned int operator()(); |
|---|
| 49 | }; |
|---|
| 50 | </pre> |
|---|
| 51 | |
|---|
| 52 | <h3>Description</h3> |
|---|
| 53 | |
|---|
| 54 | Class <code>random_device</code> models a |
|---|
| 55 | <a href="random-concepts.html#nondet-rng">non-deterministic random number |
|---|
| 56 | generator</a>. |
|---|
| 57 | It uses one or more implementation-defined stochastic processes to |
|---|
| 58 | generate a sequence of uniformly distributed non-deterministic random |
|---|
| 59 | numbers. For those environments where a non-deterministic random |
|---|
| 60 | number generator is not available, class <code>random_device</code> |
|---|
| 61 | must not be implemented. See |
|---|
| 62 | <blockquote> |
|---|
| 63 | "Randomness Recommendations for Security", D. Eastlake, S. |
|---|
| 64 | Crocker, J. Schiller, Network Working Group, RFC 1750, December 1994 |
|---|
| 65 | </blockquote> |
|---|
| 66 | for further discussions. |
|---|
| 67 | |
|---|
| 68 | <p> |
|---|
| 69 | <em>Note:</em> Some operating systems abstract the computer hardware |
|---|
| 70 | enough to make it difficult to non-intrusively monitor stochastic |
|---|
| 71 | processes. However, several do provide a special device for exactly |
|---|
| 72 | this purpose. It seems to be impossible to emulate the functionality |
|---|
| 73 | using Standard C++ only, so users should be aware that this class may |
|---|
| 74 | not be available on all platforms. |
|---|
| 75 | |
|---|
| 76 | <h3>Members</h3> |
|---|
| 77 | |
|---|
| 78 | <pre>explicit random_device(const std::string& token = default_token)</pre> |
|---|
| 79 | |
|---|
| 80 | <strong>Effects:</strong> Constructs a <code>random_device</code>, |
|---|
| 81 | optionally using the given <code>token</code> as an access |
|---|
| 82 | specification (for example, a URL) to some implementation-defined |
|---|
| 83 | service for monitoring a stochastic process. |
|---|
| 84 | |
|---|
| 85 | <pre> double entropy() const</pre> |
|---|
| 86 | <strong>Returns:</strong> An entropy estimate for the random numbers |
|---|
| 87 | returned by operator(), in the range <code>min()</code> to |
|---|
| 88 | log<sub>2</sub>( <code>max()</code>+1). A deterministic random |
|---|
| 89 | number generator (e.g. a pseudo-random number engine) has entropy 0. |
|---|
| 90 | <br> |
|---|
| 91 | <strong>Throws:</strong> Nothing. |
|---|
| 92 | |
|---|
| 93 | |
|---|
| 94 | <h3>Implementation Note for Linux</h3> |
|---|
| 95 | |
|---|
| 96 | On the Linux operating system, <code>token</code> is interpreted as a |
|---|
| 97 | filesystem path. It is assumed that this path denotes an operating |
|---|
| 98 | system pseudo-device which generates a stream of non-deterministic |
|---|
| 99 | random numbers. The pseudo-device should never signal an error or |
|---|
| 100 | end-of-file. Otherwise, <code>std::ios_base::failure</code> is |
|---|
| 101 | thrown. By default, <code>random_device</code> uses the |
|---|
| 102 | <code>/dev/urandom</code> pseudo-device to retrieve the random |
|---|
| 103 | numbers. Another option would be to specify the |
|---|
| 104 | <code>/dev/random</code> pseudo-device, which blocks on reads if the |
|---|
| 105 | entropy pool has no more random bits available. |
|---|
| 106 | |
|---|
| 107 | |
|---|
| 108 | <h2><a name="performance">Performance</a></h2> |
|---|
| 109 | |
|---|
| 110 | The test program <a href="nondet_random_speed.cpp">nondet_random_speed.cpp</a> |
|---|
| 111 | measures the execution times of the |
|---|
| 112 | <a href="../../boost/nondet_random.hpp">nondet_random.hpp</a> implementation of the above |
|---|
| 113 | algorithms in a tight loop. The performance has been evaluated on a |
|---|
| 114 | Pentium Pro 200 MHz with gcc 2.95.2, Linux 2.2.13, glibc 2.1.2. |
|---|
| 115 | |
|---|
| 116 | <p> |
|---|
| 117 | <table border=1> |
|---|
| 118 | <tr><th>class</th><th>time per invocation [usec]</th></tr> |
|---|
| 119 | <tr><td>random_device</td><td>92.0</td></tr> |
|---|
| 120 | </table> |
|---|
| 121 | |
|---|
| 122 | <p> |
|---|
| 123 | The measurement error is estimated at +/- 1 usec. |
|---|
| 124 | |
|---|
| 125 | <p> |
|---|
| 126 | <hr> |
|---|
| 127 | Jens Maurer, 2000-06-19 |
|---|
| 128 | |
|---|
| 129 | |
|---|
| 130 | </body> |
|---|
| 131 | </html> |
|---|
