Sockets/RandomNumber.h

   1 /**
   2  * @author Adam McLaurin
   3  * @date   September 2006
   4  */
   5 /*
   6 This program is free software; you can redistribute it and/or
   7 modify it under the terms of the GNU General Public License
   8 as published by the Free Software Foundation; either version 2
   9 of the License, or (at your option) any later version.
  10
  11 This program is distributed in the hope that it will be useful,
  12 but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 GNU General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with this program; if not, write to the Free Software
  18 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  19 */
  20
  21 #ifndef _SOCKET_RandomNumber_H
  22 #define _SOCKET_RandomNumber_H
  23
  24 #include "sockets-config.h"
  25 #include <limits>
  26
  27 #ifdef SOCKETS_NAMESPACE
  28 namespace SOCKETS_NAMESPACE {
  29 #endif
  30
  31 /**
  32  * The following class uses an xorshift algorithm proposed in the following
  33  * paper:
  34  *  - http://www.jstatsoft.org/v08/i14/xorshift.pdf
  35  *
  36  * The algorithm provides a PRNG with a period of (2^128)-1
  37  *
  38  * This PRNG is *not* intended for cryptographic purposes
  39  */
  40 class RandomNumber
  41 {
  42
  43 public:
  44   /**
  45    * Default constructor
  46    *
  47    * NOTE: Internal seeds are set to defaults proposed by the paper
  48    */
  49   RandomNumber(bool time_shuffle = false);
  50
  51   /**
  52    * Custom constructor
  53    *
  54    * @param x_seed X seed
  55    *
  56    * @param y_seed Y seed
  57    *
  58    * @param z_seed Z seed
  59    *
  60    * @param w_seed W seed
  61    */
  62   RandomNumber(
  63     unsigned long int x_seed,
  64     unsigned long int y_seed,
  65     unsigned long int z_seed,
  66     unsigned long int w_seed);
  67
  68   /**
  69    * Destructor
  70    */
  71   ~RandomNumber();
  72
  73   // public methods
  74
  75   /**
  76    * Reset internal state to initial seed values
  77    */
  78   void reset();
  79
  80   /**
  81    * Cast operator to obtain current random value in the PRNG
  82    *
  83    * @return Current random value in the PRNG
  84    */
  85   operator unsigned long int() const;
  86
  87   /**
  88    * Go to the next number in the PRNG sequence
  89    *
  90    * NOTE: This method is a slightly modified implementation of the xor128()
  91    * function proposed in the paper
  92    *
  93    * @return Next value produced by the PRNG (after updating)
  94    */
  95   unsigned long int next();
  96
  97   /**
  98    * Skip ahead in the PRNG sequence by a given number of iterations
  99    *
 100    * @param s Number of iterations to skip ahead
 101    *
 102    * @return Value produced by the PRNG after skipping ahead in the sequence
 103    */
 104   unsigned long int skip(unsigned long int s);
 105
 106   /**
 107    * Obtain all the initial seeds for this PRNG
 108    *
 109    * @param x_seed X seed (output)
 110    *
 111    * @param y_seed Y seed (output)
 112    *
 113    * @param z_seed Z seed (output)
 114    *
 115    * @param w_seed W seed (output)
 116    */
 117   void getSeed(
 118     unsigned long int& x_seed,
 119     unsigned long int& y_seed,
 120     unsigned long int& z_seed,
 121     unsigned long int& w_seed);
 122
 123   /**
 124    * Get the maximum possible random number from this PRNG
 125    *
 126    * @return Maximum possible random number from this PRNG
 127    */
 128   static unsigned long int max_random();
 129
 130   // public constants
 131
 132   /**
 133    * Default x-seed as proposed by the paper
 134    */
 135   static const unsigned long int X_SEED_DEFAULT;
 136
 137   /**
 138    * Default y-seed as proposed by the paper
 139    */
 140   static const unsigned long int Y_SEED_DEFAULT;
 141
 142   /**
 143    * Default z-seed as proposed by the paper
 144    */
 145   static const unsigned long int Z_SEED_DEFAULT;
 146
 147   /**
 148    * Default w-seed as proposed by the paper
 149    */
 150   static const unsigned long int W_SEED_DEFAULT;
 151
 152 private:
 153   /**
 154    * X seed
 155    */
 156   unsigned long int mXSeed;
 157
 158   /**
 159    * Y seed
 160    */
 161   unsigned long int mYSeed;
 162
 163   /**
 164    * Z seed
 165    */
 166   unsigned long int mZSeed;
 167
 168   /**
 169    * W seed
 170    */
 171   unsigned long int mWSeed;
 172
 173   /**
 174    * X value
 175    */
 176   unsigned long int mX;
 177
 178   /**
 179    * Y value
 180    */
 181   unsigned long int mY;
 182
 183   /**
 184    * Z value
 185    */
 186   unsigned long int mZ;
 187
 188   /**
 189    * W value
 190    *
 191    * NOTE: This is the externally-visible next value produced by the PRNG
 192    */
 193   unsigned long int mW;
 194
 195 };
 196
 197 #ifdef SOCKETS_NAMESPACE
 198 } // namespace SOCKETS_NAMESPACE {
 199 #endif
 200
 201 #endif // _SOCKETS_RandomNumber_H
 202