1 /*

     2  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     3  *

     4  * This code is free software; you can redistribute it and/or modify it

     5  * under the terms of the GNU General Public License version 2 only, as

     6  * published by the Free Software Foundation.  Sun designates this

     7  * particular file as subject to the "Classpath" exception as provided

     8  * by Sun in the LICENSE file that accompanied this code.

     9  *

    10  * This code is distributed in the hope that it will be useful, but WITHOUT

    11  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    12  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    13  * version 2 for more details (a copy is included in the LICENSE file that

    14  * accompanied this code).

    15  *

    16  * You should have received a copy of the GNU General Public License version

    17  * 2 along with this work; if not, write to the Free Software Foundation,

    18  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    19  *

    20  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    21  * CA 95054 USA or visit www.sun.com if you need additional information or

    22  * have any questions.

    23  */

    24 

    25 /*

    26  * This file is available under and governed by the GNU General Public

    27  * License version 2 only, as published by the Free Software Foundation.

    28  * However, the following notice accompanied the original version of this

    29  * file:

    30  *

    31  * Written by Doug Lea with assistance from members of JCP JSR-166

    32  * Expert Group and released to the public domain, as explained at

    33  * http://creativecommons.org/licenses/publicdomain

    34  */

    35 

    36 package java.util.concurrent;

    37 

    38 import java.util.Random;

    39 

    40 /**

    41  * A random number generator isolated to the current thread.  Like the

    42  * global {@link java.util.Random} generator used by the {@link

    43  * java.lang.Math} class, a {@code ThreadLocalRandom} is initialized

    44  * with an internally generated seed that may not otherwise be

    45  * modified. When applicable, use of {@code ThreadLocalRandom} rather

    46  * than shared {@code Random} objects in concurrent programs will

    47  * typically encounter much less overhead and contention.  Use of

    48  * {@code ThreadLocalRandom} is particularly appropriate when multiple

    49  * tasks (for example, each a {@link ForkJoinTask}) use random numbers

    50  * in parallel in thread pools.

    51  *

    52  * <p>Usages of this class should typically be of the form:

    53  * {@code ThreadLocalRandom.current().nextX(...)} (where

    54  * {@code X} is {@code Int}, {@code Long}, etc).

    55  * When all usages are of this form, it is never possible to

    56  * accidently share a {@code ThreadLocalRandom} across multiple threads.

    57  *

    58  * <p>This class also provides additional commonly used bounded random

    59  * generation methods.

    60  *

    61  * @since 1.7

    62  * @author Doug Lea

    63  */

    64 public class ThreadLocalRandom extends Random {

    65     // same constants as Random, but must be redeclared because private

    66     private final static long multiplier = 0x5DEECE66DL;

    67     private final static long addend = 0xBL;

    68     private final static long mask = (1L << 48) - 1;

    69 

    70     /**

    71      * The random seed. We can't use super.seed.

    72      */

    73     private long rnd;

    74 

    75     /**

    76      * Initialization flag to permit the first and only allowed call

    77      * to setSeed (inside Random constructor) to succeed.  We can't

    78      * allow others since it would cause setting seed in one part of a

    79      * program to unintentionally impact other usages by the thread.

    80      */

    81     boolean initialized;

    82 

    83     // Padding to help avoid memory contention among seed updates in

    84     // different TLRs in the common case that they are located near

    85     // each other.

    86     private long pad0, pad1, pad2, pad3, pad4, pad5, pad6, pad7;

    87 

    88     /**

    89      * The actual ThreadLocal

    90      */

    91     private static final ThreadLocal<ThreadLocalRandom> localRandom =

    92         new ThreadLocal<ThreadLocalRandom>() {

    93             protected ThreadLocalRandom initialValue() {

    94                 return new ThreadLocalRandom();

    95             }

    96     };

    97 

    98 

    99     /**

   100      * Constructor called only by localRandom.initialValue.

   101      * We rely on the fact that the superclass no-arg constructor

   102      * invokes setSeed exactly once to initialize.

   103      */

   104     ThreadLocalRandom() {

   105         super();

   106     }

   107 

   108     /**

   109      * Returns the current thread's {@code ThreadLocalRandom}.

   110      *

   111      * @return the current thread's {@code ThreadLocalRandom}

   112      */

   113     public static ThreadLocalRandom current() {

   114         return localRandom.get();

   115     }

   116 

   117     /**

   118      * Throws {@code UnsupportedOperationException}.  Setting seeds in

   119      * this generator is not supported.

   120      *

   121      * @throws UnsupportedOperationException always

   122      */

   123     public void setSeed(long seed) {

   124         if (initialized)

   125             throw new UnsupportedOperationException();

   126         initialized = true;

   127         rnd = (seed ^ multiplier) & mask;

   128     }

   129 

   130     protected int next(int bits) {

   131         rnd = (rnd * multiplier + addend) & mask;

   132         return (int) (rnd >>> (48-bits));

   133     }

   134 

   135     /**

   136      * Returns a pseudorandom, uniformly distributed value between the

   137      * given least value (inclusive) and bound (exclusive).

   138      *

   139      * @param least the least value returned

   140      * @param bound the upper bound (exclusive)

   141      * @throws IllegalArgumentException if least greater than or equal

   142      * to bound

   143      * @return the next value

   144      */

   145     public int nextInt(int least, int bound) {

   146         if (least >= bound)

   147             throw new IllegalArgumentException();

   148         return nextInt(bound - least) + least;

   149     }

   150 

   151     /**

   152      * Returns a pseudorandom, uniformly distributed value

   153      * between 0 (inclusive) and the specified value (exclusive).

   154      *

   155      * @param n the bound on the random number to be returned.  Must be

   156      *        positive.

   157      * @return the next value

   158      * @throws IllegalArgumentException if n is not positive

   159      */

   160     public long nextLong(long n) {

   161         if (n <= 0)

   162             throw new IllegalArgumentException("n must be positive");

   163         // Divide n by two until small enough for nextInt. On each

   164         // iteration (at most 31 of them but usually much less),

   165         // randomly choose both whether to include high bit in result

   166         // (offset) and whether to continue with the lower vs upper

   167         // half (which makes a difference only if odd).

   168         long offset = 0;

   169         while (n >= Integer.MAX_VALUE) {

   170             int bits = next(2);

   171             long half = n >>> 1;

   172             long nextn = ((bits & 2) == 0) ? half : n - half;

   173             if ((bits & 1) == 0)

   174                 offset += n - nextn;

   175             n = nextn;

   176         }

   177         return offset + nextInt((int) n);

   178     }

   179 

   180     /**

   181      * Returns a pseudorandom, uniformly distributed value between the

   182      * given least value (inclusive) and bound (exclusive).

   183      *

   184      * @param least the least value returned

   185      * @param bound the upper bound (exclusive)

   186      * @return the next value

   187      * @throws IllegalArgumentException if least greater than or equal

   188      * to bound

   189      */

   190     public long nextLong(long least, long bound) {

   191         if (least >= bound)

   192             throw new IllegalArgumentException();

   193         return nextLong(bound - least) + least;

   194     }

   195 

   196     /**

   197      * Returns a pseudorandom, uniformly distributed {@code double} value

   198      * between 0 (inclusive) and the specified value (exclusive).

   199      *

   200      * @param n the bound on the random number to be returned.  Must be

   201      *        positive.

   202      * @return the next value

   203      * @throws IllegalArgumentException if n is not positive

   204      */

   205     public double nextDouble(double n) {

   206         if (n <= 0)

   207             throw new IllegalArgumentException("n must be positive");

   208         return nextDouble() * n;

   209     }

   210 

   211     /**

   212      * Returns a pseudorandom, uniformly distributed value between the

   213      * given least value (inclusive) and bound (exclusive).

   214      *

   215      * @param least the least value returned

   216      * @param bound the upper bound (exclusive)

   217      * @return the next value

   218      * @throws IllegalArgumentException if least greater than or equal

   219      * to bound

   220      */

   221     public double nextDouble(double least, double bound) {

   222         if (least >= bound)

   223             throw new IllegalArgumentException();

   224         return nextDouble() * (bound - least) + least;

   225     }

   226 

   227     private static final long serialVersionUID = -5851777807851030925L;

   228 }