Oracle Coherence for C++ API
Release 3.6.0.0
E15728-01

- Main Page
- Namespaces
- Classes
- Files

# coherence/util/Random.hpp

    00001 /*
    00002 * Random.hpp
    00003 *
    00004 * Copyright (c) 2000, 2010, 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

Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.