boost/nondet_random.hpp

   1 /* boost nondet_random.hpp header file
   2  *
   3  * Copyright Jens Maurer 2000
   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  * $Id: nondet_random.hpp 62347 2010-05-31 16:44:36Z steven_watanabe $
   9  *
  10  * Revision history
  11  *  2000-02-18  Portability fixes (thanks to Beman Dawes)
  12  */
  13
  14 //  See http://www.boost.org/libs/random for documentation.
  15
  16
  17 #ifndef BOOST_NONDET_RANDOM_HPP
  18 #define BOOST_NONDET_RANDOM_HPP
  19
  20 #include <string>                       // std::abs
  21 #include <algorithm>                    // std::min
  22 #include <boost/config/no_tr1/cmath.hpp>
  23 #include <boost/config.hpp>
  24 #include <boost/utility.hpp>            // noncopyable
  25 #include <boost/integer_traits.hpp>     // compile-time integral limits
  26 #include <boost/random/detail/auto_link.hpp>
  27
  28 namespace boost {
  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  * nondet_random.hpp implementation of the above algorithms in a tight
  76  * loop. The performance has been evaluated on a Pentium Pro 200 MHz
  77  * with gcc 2.95.2, Linux 2.2.13, glibc 2.1.2.
  78  *
  79  * <table cols="2">
  80  *   <tr><th>class</th><th>time per invocation [usec]</th></tr>
  81  *   <tr><td> @xmlonly <classname alt="boost::random_device">random_device</classname> @endxmlonly </td><td>92.0</td></tr>
  82  * </table>
  83  *
  84  * The measurement error is estimated at +/- 1 usec.
  85  */
  86 class random_device : private noncopyable
  87 {
  88 public:
  89   typedef unsigned int result_type;
  90   BOOST_STATIC_CONSTANT(bool, has_fixed_range = true);
  91   BOOST_STATIC_CONSTANT(result_type, min_value = integer_traits<result_type>::const_min);
  92   BOOST_STATIC_CONSTANT(result_type, max_value = integer_traits<result_type>::const_max);
  93
  94   /**
  95    * Returns: The smallest value that the \random_device can produce.
  96    */
  97   result_type min BOOST_PREVENT_MACRO_SUBSTITUTION () const { return min_value; }
  98   /**
  99    * Returns: The largest value that the \random_device can produce.
 100    */
 101   result_type max BOOST_PREVENT_MACRO_SUBSTITUTION () const { return max_value; }
 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 = default_token);
 108   BOOST_RANDOM_DECL ~random_device();
 109   /**
 110    * Returns: An entropy estimate for the random numbers returned by
 111    * operator(), in the range min() to log2( max()+1). A deterministic
 112    * random number generator (e.g. a pseudo-random number engine)
 113    * has entropy 0.
 114    *
 115    * Throws: Nothing.
 116    */
 117   BOOST_RANDOM_DECL double entropy() const;
 118   /**
 119    * Returns: A random value in the range [min, max]
 120    */
 121   BOOST_RANDOM_DECL unsigned int operator()();
 122
 123 private:
 124   BOOST_RANDOM_DECL static const char * const default_token;
 125
 126   /*
 127    * std:5.3.5/5 [expr.delete]: "If the object being deleted has incomplete
 128    * class type at the point of deletion and the complete class has a
 129    * non-trivial destructor [...], the behavior is undefined".
 130    * This disallows the use of scoped_ptr<> with pimpl-like classes
 131    * having a non-trivial destructor.
 132    */
 133   class impl;
 134   impl * pimpl;
 135 };
 136
 137
 138 // TODO: put Schneier's Yarrow-160 algorithm here.
 139
 140 } // namespace boost
 141
 142 #endif /* BOOST_NONDET_RANDOM_HPP */