00001 /* 00002 * Random.hpp 00003 * 00004 * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. 00005 * 00006 * Oracle is a registered trademarks of Oracle Corporation and/or its 00007 * affiliates. 00008 * 00009 * This software is the confidential and proprietary information of Oracle 00010 * Corporation. You shall not disclose such confidential and proprietary 00011 * information and shall use it only in accordance with the terms of the 00012 * license agreement you entered into with Oracle. 00013 * 00014 * This notice may not be removed or altered. 00015 */ 00016 #ifndef COH_RANDOM_HPP 00017 #define COH_RANDOM_HPP 00018 00019 #include "coherence/lang.ns" 00020 00021 #include "coherence/native/NativeAtomic64.hpp" 00022 #include "coherence/util/List.hpp" 00023 00024 COH_OPEN_NAMESPACE2(coherence,util) 00025 00026 using coherence::native::NativeAtomic64; 00027 using coherence::util::List; 00028 00029 00030 /** 00031 * An instance of this class is used to generate a stream of pseudorandom 00032 * numbers. This class is an implementation of D. H. Lehmer's linear 00033 * congruential formula as described by Donald E. Knuth in: 00034 * The Art of Computer Programming, Volume 2, Section 3.2.1. 00035 * 00036 * @author js 2008.03.27 00037 */ 00038 class COH_EXPORT Random 00039 : public class_spec<Random> 00040 { 00041 friend class factory<Random>; 00042 00043 // ----- constructors --------------------------------------------------- 00044 00045 protected: 00046 /** 00047 * Create a new Random instance without supplying a seed. The seed 00048 * will be initialized by the default algorithm provided in seed(). 00049 */ 00050 Random(); 00051 00052 /** 00053 * Create a new Random instance, specifying a seed to use. 00054 */ 00055 Random(int64_t lSeed); 00056 00057 00058 // ----- Random interface ----------------------------------------------- 00059 00060 public: 00061 /** 00062 * Returns a pseudorandom, uniformly distributed int value between 0 00063 * (inclusive) and the specified value (exclusive), drawn from this 00064 * random number generator's sequence. 00065 * 00066 * @paran n the upper bound (exclusive) for the returned value 00067 * 00068 * @return an int32_t value in the range [0, n) 00069 * 00070 * @throws IllegalArgumentException if n is <= 0 00071 */ 00072 virtual int32_t nextInt32(int32_t n); 00073 00074 /** 00075 * Returns the next pseudorandom, uniformly distributed boolean value 00076 * from this random number generator's sequence. 00077 * 00078 * @return the next bool value 00079 */ 00080 virtual bool nextBoolean(); 00081 00082 /** 00083 * Returns the next pseudorandom, uniformly distributed int32_t value 00084 * from this random number generator's sequence. 00085 * 00086 * @return the next int32_t value in the range [Integer32::min_value, 00087 * Integer32::max_value] 00088 */ 00089 virtual int32_t nextInt32(); 00090 00091 /** 00092 * Returns the next pseudorandom, uniformly distributed int64_t value 00093 * from this random number generator's sequence. 00094 * 00095 * @return the next int64_t value in the range [Integer64::min_value, 00096 * Integer64::max_value] 00097 */ 00098 virtual int64_t nextInt64(); 00099 00100 /** 00101 * Returns the next pseudorandom, uniformly distributed float32_t 00102 * value from this random number generator's sequence. 00103 * 00104 * @return the next float32_t value in the range [0.0, 1.0] 00105 */ 00106 virtual float32_t nextFloat32(); 00107 00108 /** 00109 * Returns the next pseudorandom, uniformly distributed float64_t 00110 * value from this random number generator's sequence. 00111 * 00112 * @return the next float64_t value in the range [0.0, 1.0] 00113 */ 00114 virtual float64_t nextFloat64(); 00115 00116 /** 00117 * Provides a default seeding algorithm that is used to seed this 00118 * random number if no seed is provided. 00119 */ 00120 virtual void seed(); 00121 00122 /** 00123 * Sets the seed of this random number generator using a single long 00124 * seed. 00125 */ 00126 virtual void setSeed(int64_t lSeed); 00127 00128 00129 // ----- helper methods ------------------------------------------------- 00130 00131 public: 00132 /** 00133 * Randomize the order of the elements within the passed array. 00134 * 00135 * @param ha an array of objects to randomize 00136 * 00137 * @return the array that was passed in, with its contents 00138 * unchanged except for the order in which they appear 00139 * 00140 * @since Coherence 3.2 00141 */ 00142 static ObjectArray::Handle randomize(ObjectArray::Handle ha); 00143 00144 /** 00145 * Randomize the order of the elements within the passed list. 00146 * 00147 * @param ha a list of objects to randomize 00148 * 00149 * @return the list that was passed in, with its contents 00150 * unchanged except for the order in which they appear 00151 * 00152 * @since Coherence 3.4 00153 */ 00154 static List::Handle randomize(List::Handle hl); 00155 00156 protected: 00157 /** 00158 * Implementation of the random number algorithm which generates the 00159 * next pseudorandom number. 00160 * <p> 00161 * Generates a 32 bit int value with it's corresponding bits being 00162 * individually generated pseudorandom 1's and 0's. This method 00163 * should be overridden to provide a new random number algorithm. 00164 * 00165 * @param nBits number of random bits to generate 00166 * 00167 * @return the next pseudorandom number with the specified number of 00168 * randomly generated bits 00169 */ 00170 virtual int32_t next(int32_t nBits); 00171 00172 00173 // ----- constants ------------------------------------------------------ 00174 00175 public: 00176 /** 00177 * Return the static Random instance. 00178 * 00179 * @return the static Random instance 00180 */ 00181 static Handle getInstance(); 00182 00183 00184 // ----- data members --------------------------------------------------- 00185 00186 protected: 00187 /** 00188 * The internal state associated with this pseudorandom number 00189 * generator. 00190 */ 00191 NativeAtomic64 m_atomicSeed; 00192 }; 00193 00194 COH_CLOSE_NAMESPACE2 00195 00196 #endif // COH_RANDOM_HPP 00197