/Src/Dependencies/Boost/boost/random/random_device.hpp

http://hadesmem.googlecode.com/ · C++ Header · 142 lines · 35 code · 16 blank · 91 comment · 2 complexity · ede3cf6d3d93f4e9a807206e167e48b6 MD5 · raw file

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