]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/ |
2 | / Copyright (c) 2009 Steven Watanabe | |
3 | / | |
4 | / Distributed under the Boost Software License, Version 1.0. (See | |
5 | / accompanying file LICENSE_1_0.txt or copy at | |
6 | / http://www.boost.org/LICENSE_1_0.txt) | |
7 | ] | |
8 | ||
9 | [section Header <boost/nondet_random.hpp> Synopsis] | |
10 | ||
11 | namespace boost { | |
12 | class random_device; | |
13 | } // namespace boost | |
14 | ||
15 | [endsect] | |
16 | ||
17 | [section Class random_device] | |
18 | ||
19 | [section Synopsis] | |
20 | ||
21 | class random_device : noncopyable | |
22 | { | |
23 | public: | |
24 | typedef unsigned int result_type; | |
25 | static const bool has_fixed_range = true; | |
26 | static const result_type min_value = /* implementation defined */; | |
27 | static const result_type max_value = /* implementation defined */; | |
28 | result_type min() const; | |
29 | result_type max() const; | |
30 | explicit random_device(const std::string& token = default_token); | |
31 | ~random_device(); | |
32 | double entropy() const; | |
33 | unsigned int operator()(); | |
34 | }; | |
35 | ||
36 | [endsect] | |
37 | ||
38 | [section Description] | |
39 | ||
40 | Class `random_device` models a non-deterministic random number generator. It | |
41 | uses one or more implementation-defined stochastic processes to generate a | |
42 | sequence of uniformly distributed non-deterministic random numbers. For those | |
43 | environments where a non-deterministic random number generator is not | |
44 | available, class random_device must not be implemented. See | |
45 | ||
46 | [:"Randomness Recommendations for Security", D. Eastlake, S. Crocker, | |
47 | J. Schiller, Network Working Group, RFC 1750, December 1994] | |
48 | ||
49 | for further discussions. | |
50 | ||
51 | [note Some operating systems abstract the computer hardware enough to make it | |
52 | difficult to non-intrusively monitor stochastic processes. However, several do | |
53 | provide a special device for exactly this purpose. It seems to be impossible | |
54 | to emulate the functionality using Standard C++ only, so users should be aware | |
55 | that this class may not be available on all platforms.] | |
56 | ||
57 | [endsect] | |
58 | ||
59 | [section Members] | |
60 | ||
61 | explicit random_device(const std::string& token = default_token) | |
62 | ||
63 | Effects: Constructs a random_device, optionally using the given token as an | |
64 | access specification (for example, a URL) to some implementation-defined | |
65 | service for monitoring a stochastic process. | |
66 | ||
67 | double entropy() const | |
68 | ||
69 | Returns: An entropy estimate for the random numbers returned by `operator()`, | |
70 | in the range `min()` to `log2(max()+1)`. A deterministic random number | |
71 | generator (e.g. a pseudo-random number engine) has entropy 0. | |
72 | ||
73 | Throws: Nothing. | |
74 | ||
75 | [endsect] | |
76 | ||
77 | Implementation Note for Linux | |
78 | On the Linux operating system, token is interpreted as a filesystem path. It | |
79 | is assumed that this path denotes an operating system pseudo-device which | |
80 | generates a stream of non-deterministic random numbers. The pseudo-device | |
81 | should never signal an error or end-of-file. Otherwise, std::ios_base::failure | |
82 | is thrown. By default, random_device uses the /dev/urandom pseudo-device to | |
83 | retrieve the random numbers. Another option would be to specify the | |
84 | /dev/random pseudo-device, which blocks on reads if the entropy pool has no | |
85 | more random bits available. | |
86 | ||
87 | [endsect] | |
88 | ||
89 | [section Performance] | |
90 | ||
91 | The test program nondet_random_speed.cpp measures the execution times of the | |
92 | nondet_random.hpp implementation of the above algorithms in a tight loop. | |
93 | The performance has been evaluated on a Pentium Pro 200 MHz with gcc 2.95.2, | |
94 | Linux 2.2.13, glibc 2.1.2. | |
95 | ||
96 | [table preformance | |
97 | [[class] [time per invocation \[usec\]]] | |
98 | [[random_device] [92.0]] | |
99 | ] | |
100 | ||
101 | The measurement error is estimated at +/- 1 usec. | |
102 | ||
103 | [endsect] |