ceph/src/boost/libs/random/doc/nondet_random.qbk

   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]