jdk-sandbox: src/java.base/share/classes/java/util/random/StreamableRNG.java@f02ffcb61dce (annotated)

57388 b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	1	/*
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	2	* Copyright (c) 2013, 2019, Oracle and/or its affiliates. All rights reserved.
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	3	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	4	*
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	5	* This code is free software; you can redistribute it and/or modify it
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	6	* under the terms of the GNU General Public License version 2 only, as
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	7	* published by the Free Software Foundation. Oracle designates this
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	8	* particular file as subject to the "Classpath" exception as provided
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	9	* by Oracle in the LICENSE file that accompanied this code.
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	10	*
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	11	* This code is distributed in the hope that it will be useful, but WITHOUT
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	12	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	13	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	14	* version 2 for more details (a copy is included in the LICENSE file that
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	15	* accompanied this code).
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	16	*
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	17	* You should have received a copy of the GNU General Public License version
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	18	* 2 along with this work; if not, write to the Free Software Foundation,
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	19	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	20	*
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	21	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	22	* or visit www.oracle.com if you need additional information or have any
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	23	* questions.
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	24	*/
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	25
57437 f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	26	package java.util.random;
f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	27
57388 b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	28	import java.util.stream.Stream;
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	29
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	30
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	31	/**
57437 f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	32	* The {@link StreamableRNG} interface augments the {@link RandomNumberGenerator} interface
f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	33	* to provide methods that return streams of {@link RandomNumberGenerator} objects.
57388 b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	34	* Ideally, such a stream of objects would have the property that the
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	35	* behavior of each object is statistically independent of all the others.
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	36	* In practice, one may have to settle for some approximation to this property.
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	37	*
57437 f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	38	* A generator that implements interface {@link SplittableRNG}
57388 b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	39	* may choose to use its {@code splits} method to implement the {@code rngs}
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	40	* method required by this interface.
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	41	*
57437 f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	42	* A generator that implements interface {@link JumpableRNG}
57388 b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	43	* may choose to use its {@code jumps} method to implement the {@code rngs}
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	44	* method required by this interface.
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	45	*
57437 f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	46	* A generator that implements interface {@link LeapableRNG}
57388 b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	47	* may choose to use its {@code leaps} method to implement the {@code rngs}
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	48	* method required by this interface.
57437 f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	49	* <p>
f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	50	* An implementation of the {@link StreamableRNG} interface must provide
57388 b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	51	* concrete definitions for the methods {@code nextInt()}, {@code nextLong},
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	52	* {@code period()}, and {@code rngs()}.
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	53	* Default implementations are provided for all other methods.
57437 f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	54	* <p>
f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	55	* Objects that implement {@link StreamableRNG} are typically
57388 b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	56	* not cryptographically secure. Consider instead using
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	57	* {@link java.security.SecureRandom} to get a cryptographically
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	58	* secure pseudo-random number generator for use by
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	59	* security-sensitive applications.
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	60	*
57437 f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	61	* @since 14
57388 b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	62	*/
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	63
57437 f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	64	public interface StreamableRNG extends RandomNumberGenerator {
57388 b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	65	/**
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	66	* Returns an effectively unlimited stream of objects, each of
57437 f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	67	* which implements the {@link RandomNumberGenerator} interface. Ideally the
57388 b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	68	* generators in the stream will appear to be statistically
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	69	* independent. The new generators should be of the same kind
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	70	* as this generator.
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	71	*
57437 f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	72	* @return a stream of objects that implement the {@link RandomNumberGenerator} interface
57388 b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	73	*
57437 f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	74	* @implNote It is permitted to implement this method in a manner
f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	75	* equivalent to {@code rngs(Long.MAX_VALUE)}.
57388 b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	76	*/
57437 f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	77	Stream<RandomNumberGenerator> rngs();
57388 b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	78
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	79	/**
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	80	* Returns an effectively unlimited stream of objects, each of
57437 f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	81	* which implements the {@link RandomNumberGenerator} interface. Ideally the
57388 b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	82	* generators in the stream will appear to be statistically
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	83	* independent. The new generators should be of the same kind
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	84	* as this generator.
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	85	*
57437 f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	86	* @param streamSize the number of generators to generate
57388 b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	87	*
57437 f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	88	* @return a stream of objects that implement the {@link RandomNumberGenerator} interface
f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	89	*
57388 b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	90	* @throws IllegalArgumentException if {@code streamSize} is
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	91	* less than zero
57437 f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	92	*
f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	93	* @implNote The default implementation calls {@code rngs()} and
f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	94	* then limits its length to {@code streamSize}.
57388 b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	95	*/
57437 f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	96	default Stream<RandomNumberGenerator> rngs(long streamSize) {
f02ffcb61dce Rename Rng.java to RandomNumberGenerator.java, clean up javadoc and misc code changes jlaskey parents: 57436 diff changeset	97	RNGSupport.checkStreamSize(streamSize);
57388 b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	98	return rngs().limit(streamSize);
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	99	}
b1e6bc96af3d Initial commit of new RNG code from GLS briangoetz parents: diff changeset	100	}

author	jlaskey
	Thu, 27 Jun 2019 18:30:27 -0300
branch	JDK-8193209-branch
changeset 57437	f02ffcb61dce
parent 57436	b0c958c0e6c6
permissions	-rw-r--r--