mirror of
https://github.com/openjdk/jdk.git
synced 2026-01-28 20:18:48 +00:00
757 lines
33 KiB
Java
757 lines
33 KiB
Java
/*
|
|
* Copyright (c) 2025, Oracle and/or its affiliates. All rights reserved.
|
|
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
|
*
|
|
* This code is free software; you can redistribute it and/or modify it
|
|
* under the terms of the GNU General Public License version 2 only, as
|
|
* published by the Free Software Foundation. Oracle designates this
|
|
* particular file as subject to the "Classpath" exception as provided
|
|
* by Oracle in the LICENSE file that accompanied this code.
|
|
*
|
|
* This code is distributed in the hope that it will be useful, but WITHOUT
|
|
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
|
* version 2 for more details (a copy is included in the LICENSE file that
|
|
* accompanied this code).
|
|
*
|
|
* You should have received a copy of the GNU General Public License version
|
|
* 2 along with this work; if not, write to the Free Software Foundation,
|
|
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
|
*
|
|
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
|
|
* or visit www.oracle.com if you need additional information or have any
|
|
* questions.
|
|
*/
|
|
|
|
package java.lang;
|
|
|
|
import jdk.internal.access.SharedSecrets;
|
|
import jdk.internal.javac.PreviewFeature;
|
|
import jdk.internal.lang.stable.StableEnumFunction;
|
|
import jdk.internal.lang.stable.StableFunction;
|
|
import jdk.internal.lang.stable.StableIntFunction;
|
|
import jdk.internal.lang.stable.StableSupplier;
|
|
import jdk.internal.lang.stable.StableUtil;
|
|
import jdk.internal.lang.stable.StableValueImpl;
|
|
|
|
import java.io.Serializable;
|
|
import java.util.Collection;
|
|
import java.util.EnumSet;
|
|
import java.util.List;
|
|
import java.util.Map;
|
|
import java.util.NoSuchElementException;
|
|
import java.util.Objects;
|
|
import java.util.RandomAccess;
|
|
import java.util.Set;
|
|
import java.util.function.Function;
|
|
import java.util.function.IntFunction;
|
|
import java.util.function.Supplier;
|
|
|
|
/**
|
|
* A stable value is a holder of contents that can be set at most once.
|
|
* <p>
|
|
* A {@code StableValue<T>} is typically created using the factory method
|
|
* {@linkplain StableValue#of() {@code StableValue.of()}}. When created this way,
|
|
* the stable value is <em>unset</em>, which means it holds no <em>contents</em>.
|
|
* Its contents, of type {@code T}, can be <em>set</em> by calling
|
|
* {@linkplain #trySet(Object) trySet()}, {@linkplain #setOrThrow(Object) setOrThrow()},
|
|
* or {@linkplain #orElseSet(Supplier) orElseSet()}. Once set, the contents
|
|
* can never change and can be retrieved by calling {@linkplain #orElseThrow() orElseThrow()}
|
|
* , {@linkplain #orElse(Object) orElse()}, or {@linkplain #orElseSet(Supplier) orElseSet()}.
|
|
* <p>
|
|
* Consider the following example where a stable value field "{@code logger}" is a
|
|
* shallowly immutable holder of contents of type {@code Logger} and that is initially
|
|
* created as <em>unset</em>, which means it holds no contents. Later in the example, the
|
|
* state of the "{@code logger}" field is checked and if it is still <em>unset</em>,
|
|
* the contents is <em>set</em>:
|
|
*
|
|
* {@snippet lang = java:
|
|
* public class Component {
|
|
*
|
|
* // Creates a new unset stable value with no contents
|
|
* // @link substring="of" target="#of" :
|
|
* private final StableValue<Logger> logger = StableValue.of();
|
|
*
|
|
* private Logger getLogger() {
|
|
* if (!logger.isSet()) {
|
|
* logger.trySet(Logger.create(Component.class));
|
|
* }
|
|
* return logger.orElseThrow();
|
|
* }
|
|
*
|
|
* public void process() {
|
|
* getLogger().info("Process started");
|
|
* // ...
|
|
* }
|
|
* }
|
|
*}
|
|
* <p>
|
|
* If {@code getLogger()} is called from several threads, several instances of
|
|
* {@code Logger} might be created. However, the contents can only be set at most once
|
|
* meaning the first writer wins.
|
|
* <p>
|
|
* In order to guarantee that, even under races, only one instance of {@code Logger} is
|
|
* ever created, the {@linkplain #orElseSet(Supplier) orElseSet()} method can be used
|
|
* instead, where the contents are lazily computed, and atomically set, via a
|
|
* {@linkplain Supplier supplier}. In the example below, the supplier is provided in the
|
|
* form of a lambda expression:
|
|
*
|
|
* {@snippet lang = java:
|
|
* public class Component {
|
|
*
|
|
* // Creates a new unset stable value with no contents
|
|
* // @link substring="of" target="#of" :
|
|
* private final StableValue<Logger> logger = StableValue.of();
|
|
*
|
|
* private Logger getLogger() {
|
|
* return logger.orElseSet( () -> Logger.create(Component.class) );
|
|
* }
|
|
*
|
|
* public void process() {
|
|
* getLogger().info("Process started");
|
|
* // ...
|
|
* }
|
|
* }
|
|
*}
|
|
* <p>
|
|
* The {@code getLogger()} method calls {@code logger.orElseSet()} on the stable value to
|
|
* retrieve its contents. If the stable value is <em>unset</em>, then {@code orElseSet()}
|
|
* evaluates the given supplier, and sets the contents to the result; the result is then
|
|
* returned to the client. In other words, {@code orElseSet()} guarantees that a
|
|
* stable value's contents is <em>set</em> before it returns.
|
|
* <p>
|
|
* Furthermore, {@code orElseSet()} guarantees that out of one or more suppliers provided,
|
|
* only at most one is ever evaluated, and that one is only ever evaluated once,
|
|
* even when {@code logger.orElseSet()} is invoked concurrently. This property is crucial
|
|
* as evaluation of the supplier may have side effects, for example, the call above to
|
|
* {@code Logger.create()} may result in storage resources being prepared.
|
|
*
|
|
* <h2 id="stable-functions">Stable Functions</h2>
|
|
* Stable values provide the foundation for higher-level functional abstractions. A
|
|
* <em>stable supplier</em> is a supplier that computes a value and then caches it into
|
|
* a backing stable value storage for subsequent use. A stable supplier is created via the
|
|
* {@linkplain StableValue#supplier(Supplier) StableValue.supplier()} factory, by
|
|
* providing an underlying {@linkplain Supplier} which is invoked when the stable supplier
|
|
* is first accessed:
|
|
*
|
|
* {@snippet lang = java:
|
|
* public class Component {
|
|
*
|
|
* private final Supplier<Logger> logger =
|
|
* // @link substring="supplier" target="#supplier(Supplier)" :
|
|
* StableValue.supplier( () -> Logger.getLogger(Component.class) );
|
|
*
|
|
* public void process() {
|
|
* logger.get().info("Process started");
|
|
* // ...
|
|
* }
|
|
* }
|
|
*}
|
|
* A stable supplier encapsulates access to its backing stable value storage. This means
|
|
* that code inside {@code Component} can obtain the logger object directly from the
|
|
* stable supplier, without having to go through an accessor method like {@code getLogger()}.
|
|
* <p>
|
|
* A <em>stable int function</em> is a function that takes an {@code int} parameter and
|
|
* uses it to compute a result that is then cached by the backing stable value storage
|
|
* for that parameter value. A stable {@link IntFunction} is created via the
|
|
* {@linkplain StableValue#intFunction(int, IntFunction) StableValue.intFunction()}
|
|
* factory. Upon creation, the input range (i.e. {@code [0, size)}) is specified together
|
|
* with an underlying {@linkplain IntFunction} which is invoked at most once per input
|
|
* value. In effect, the stable int function will act like a cache for the underlying
|
|
* {@linkplain IntFunction}:
|
|
*
|
|
* {@snippet lang = java:
|
|
* final class PowerOf2Util {
|
|
*
|
|
* private PowerOf2Util() {}
|
|
*
|
|
* private static final int SIZE = 6;
|
|
* private static final IntFunction<Integer> UNDERLYING_POWER_OF_TWO =
|
|
* v -> 1 << v;
|
|
*
|
|
* private static final IntFunction<Integer> POWER_OF_TWO =
|
|
* // @link substring="intFunction" target="#intFunction(int,IntFunction)" :
|
|
* StableValue.intFunction(SIZE, UNDERLYING_POWER_OF_TWO);
|
|
*
|
|
* public static int powerOfTwo(int a) {
|
|
* return POWER_OF_TWO.apply(a);
|
|
* }
|
|
* }
|
|
*
|
|
* int result = PowerOf2Util.powerOfTwo(4); // May eventually constant fold to 16 at runtime
|
|
*
|
|
*}
|
|
* The {@code PowerOf2Util.powerOfTwo()} function is a <em>partial function</em> that only
|
|
* allows a subset {@code [0, 5]} of the underlying function's {@code UNDERLYING_POWER_OF_TWO}
|
|
* input range.
|
|
*
|
|
* <p>
|
|
* A <em>stable function</em> is a function that takes a parameter (of type {@code T}) and
|
|
* uses it to compute a result (of type {@code R}) that is then cached by the backing
|
|
* stable value storage for that parameter value. A stable function is created via the
|
|
* {@linkplain StableValue#function(Set, Function) StableValue.function()} factory.
|
|
* Upon creation, the input {@linkplain Set} is specified together with an underlying
|
|
* {@linkplain Function} which is invoked at most once per input value. In effect, the
|
|
* stable function will act like a cache for the underlying {@linkplain Function}:
|
|
*
|
|
* {@snippet lang = java:
|
|
* class Log2Util {
|
|
*
|
|
* private Log2Util() {}
|
|
*
|
|
* private static final Set<Integer> KEYS =
|
|
* Set.of(1, 2, 4, 8, 16, 32);
|
|
* private static final UnaryOperator<Integer> UNDERLYING_LOG2 =
|
|
* i -> 31 - Integer.numberOfLeadingZeros(i);
|
|
*
|
|
* private static final Function<Integer, Integer> LOG2 =
|
|
* // @link substring="function" target="#function(Set,Function)" :
|
|
* StableValue.function(KEYS, UNDERLYING_LOG2);
|
|
*
|
|
* public static int log2(int a) {
|
|
* return LOG2.apply(a);
|
|
* }
|
|
*
|
|
* }
|
|
*
|
|
* int result = Log2Util.log2(16); // May eventually constant fold to 4 at runtime
|
|
*}
|
|
*
|
|
* The {@code Log2Util.log2()} function is a <em>partial function</em> that only allows
|
|
* a subset {@code {1, 2, 4, 8, 16, 32}} of the underlying function's
|
|
* {@code UNDERLYING_LOG2} input range.
|
|
*
|
|
* <h2 id="stable-collections">Stable Collections</h2>
|
|
* Stable values can also be used as backing storage for
|
|
* {@linkplain Collection##unmodifiable unmodifiable collections}. A <em>stable list</em>
|
|
* is an unmodifiable list, backed by an array of stable values. The stable list elements
|
|
* are computed when they are first accessed, using a provided {@linkplain IntFunction}:
|
|
*
|
|
* {@snippet lang = java:
|
|
* final class PowerOf2Util {
|
|
*
|
|
* private PowerOf2Util() {}
|
|
*
|
|
* private static final int SIZE = 6;
|
|
* private static final IntFunction<Integer> UNDERLYING_POWER_OF_TWO =
|
|
* v -> 1 << v;
|
|
*
|
|
* private static final List<Integer> POWER_OF_TWO =
|
|
* // @link substring="list" target="#list(int,IntFunction)" :
|
|
* StableValue.list(SIZE, UNDERLYING_POWER_OF_TWO);
|
|
*
|
|
* public static int powerOfTwo(int a) {
|
|
* return POWER_OF_TWO.get(a);
|
|
* }
|
|
* }
|
|
*
|
|
* int result = PowerOf2Util.powerOfTwo(4); // May eventually constant fold to 16 at runtime
|
|
*
|
|
* }
|
|
* <p>
|
|
* Similarly, a <em>stable map</em> is an unmodifiable map whose keys are known at
|
|
* construction. The stable map values are computed when they are first accessed,
|
|
* using a provided {@linkplain Function}:
|
|
*
|
|
* {@snippet lang = java:
|
|
* class Log2Util {
|
|
*
|
|
* private Log2Util() {}
|
|
*
|
|
* private static final Set<Integer> KEYS =
|
|
* Set.of(1, 2, 4, 8, 16, 32);
|
|
* private static final UnaryOperator<Integer> UNDERLYING_LOG2 =
|
|
* i -> 31 - Integer.numberOfLeadingZeros(i);
|
|
*
|
|
* private static final Map<Integer, INTEGER> LOG2 =
|
|
* // @link substring="map" target="#map(Set,Function)" :
|
|
* StableValue.map(CACHED_KEYS, UNDERLYING_LOG2);
|
|
*
|
|
* public static int log2(int a) {
|
|
* return LOG2.get(a);
|
|
* }
|
|
*
|
|
* }
|
|
*
|
|
* int result = Log2Util.log2(16); // May eventually constant fold to 4 at runtime
|
|
*
|
|
*}
|
|
*
|
|
* <h2 id="composition">Composing stable values</h2>
|
|
* A stable value can depend on other stable values, forming a dependency graph
|
|
* that can be lazily computed but where access to individual elements can still be
|
|
* performant. In the following example, a single {@code Foo} and a {@code Bar}
|
|
* instance (that is dependent on the {@code Foo} instance) are lazily created, both of
|
|
* which are held by stable values:
|
|
* {@snippet lang = java:
|
|
* public final class DependencyUtil {
|
|
*
|
|
* private DependencyUtil() {}
|
|
*
|
|
* public static class Foo {
|
|
* // ...
|
|
* }
|
|
*
|
|
* public static class Bar {
|
|
* public Bar(Foo foo) {
|
|
* // ...
|
|
* }
|
|
* }
|
|
*
|
|
* private static final Supplier<Foo> FOO = StableValue.supplier(Foo::new);
|
|
* private static final Supplier<Bar> BAR = StableValue.supplier(() -> new Bar(FOO.get()));
|
|
*
|
|
* public static Foo foo() {
|
|
* return FOO.get();
|
|
* }
|
|
*
|
|
* public static Bar bar() {
|
|
* return BAR.get();
|
|
* }
|
|
*
|
|
* }
|
|
*}
|
|
* Calling {@code bar()} will create the {@code Bar} singleton if it is not already
|
|
* created. Upon such a creation, the dependent {@code Foo} will first be created if
|
|
* the {@code Foo} does not already exist.
|
|
* <p>
|
|
* Another example, which has a more complex dependency graph, is to compute the
|
|
* Fibonacci sequence lazily:
|
|
* {@snippet lang = java:
|
|
* public final class Fibonacci {
|
|
*
|
|
* private Fibonacci() {}
|
|
*
|
|
* private static final int MAX_SIZE_INT = 46;
|
|
*
|
|
* private static final IntFunction<Integer> FIB =
|
|
* StableValue.intFunction(MAX_SIZE_INT, Fibonacci::fib);
|
|
*
|
|
* public static int fib(int n) {
|
|
* return n < 2
|
|
* ? n
|
|
* : FIB.apply(n - 1) + FIB.apply(n - 2);
|
|
* }
|
|
*
|
|
* }
|
|
*}
|
|
* Both {@code FIB} and {@code Fibonacci::fib} recurse into each other. Because the
|
|
* stable int function {@code FIB} caches intermediate results, the initial
|
|
* computational complexity is reduced from exponential to linear compared to a
|
|
* traditional non-caching recursive fibonacci method. Once computed, the VM is free to
|
|
* constant-fold expressions like {@code Fibonacci.fib(5)}.
|
|
* <p>
|
|
* The fibonacci example above is a directed acyclic graph (i.e.,
|
|
* it has no circular dependencies and is therefore a dependency tree):
|
|
*{@snippet lang=text :
|
|
*
|
|
* ___________fib(5)____________
|
|
* / \
|
|
* ____fib(4)____ ____fib(3)____
|
|
* / \ / \
|
|
* fib(3) fib(2) fib(2) fib(1)
|
|
* / \ / \ / \
|
|
* fib(2) fib(1) fib(1) fib(0) fib(1) fib(0)
|
|
*}
|
|
*
|
|
* If there are circular dependencies in a dependency graph, a stable value will
|
|
* eventually throw an {@linkplain IllegalStateException} upon referencing elements in
|
|
* a circularity.
|
|
*
|
|
* <h2 id="thread-safety">Thread Safety</h2>
|
|
* The contents of a stable value is guaranteed to be set at most once. If competing
|
|
* threads are racing to set a stable value, only one update succeeds, while the other
|
|
* updates are blocked until the stable value is set, whereafter the other updates
|
|
* observes the stable value is set and leave the stable value unchanged.
|
|
* <p>
|
|
* The at-most-once write operation on a stable value that succeeds
|
|
* (e.g. {@linkplain #trySet(Object) trySet()})
|
|
* {@linkplain java.util.concurrent##MemoryVisibility <em>happens-before</em>}
|
|
* any successful read operation (e.g. {@linkplain #orElseThrow()}).
|
|
* A successful write operation can be either:
|
|
* <ul>
|
|
* <li>a {@link #trySet(Object)} that returns {@code true},</li>
|
|
* <li>a {@link #setOrThrow(Object)} that does not throw, or</li>
|
|
* <li>an {@link #orElseSet(Supplier)} that successfully runs the supplier</li>
|
|
* </ul>
|
|
* A successful read operation can be either:
|
|
* <ul>
|
|
* <li>a {@link #orElseThrow()} that does not throw,</li>
|
|
* <li>a {@link #orElse(Object) orElse(other)} that does not return the {@code other} value</li>
|
|
* <li>an {@link #orElseSet(Supplier)} that does not {@code throw}, or</li>
|
|
* <li>an {@link #isSet()} that returns {@code true}</li>
|
|
* </ul>
|
|
* <p>
|
|
* The method {@link #orElseSet(Supplier)} guarantees that the provided
|
|
* {@linkplain Supplier} is invoked successfully at most once, even under race.
|
|
* Invocations of {@link #orElseSet(Supplier)} form a total order of zero or
|
|
* more exceptional invocations followed by zero (if the contents were already set) or one
|
|
* successful invocation. Since stable functions and stable collections are built on top
|
|
* of the same principles as {@linkplain StableValue#orElseSet(Supplier) orElseSet()} they
|
|
* too are thread safe and guarantee at-most-once-per-input invocation.
|
|
*
|
|
* <h2 id="performance">Performance</h2>
|
|
* As the contents of a stable value can never change after it has been set, a JVM
|
|
* implementation may, for a set stable value, elide all future reads of that
|
|
* stable value, and instead directly use any contents that it has previously observed.
|
|
* This is true if the reference to the stable value is a constant (e.g. in cases where
|
|
* the stable value itself is stored in a {@code static final} field). Stable functions
|
|
* and collections are built on top of StableValue. As such, they might also be eligible
|
|
* for the same JVM optimizations as for StableValue.
|
|
*
|
|
* @implSpec Implementing classes of {@code StableValue} are free to synchronize on
|
|
* {@code this} and consequently, it should be avoided to
|
|
* (directly or indirectly) synchronize on a {@code StableValue}. Hence,
|
|
* synchronizing on {@code this} may lead to deadlock.
|
|
* <p>
|
|
* Except for a {@code StableValue}'s contents itself,
|
|
* an {@linkplain #orElse(Object) orElse(other)} parameter, and
|
|
* an {@linkplain #equals(Object) equals(obj)} parameter; all
|
|
* method parameters must be <em>non-null</em> or a {@link NullPointerException}
|
|
* will be thrown.
|
|
*
|
|
* @implNote A {@code StableValue} is mainly intended to be a non-public field in
|
|
* a class and is usually neither exposed directly via accessors nor passed as
|
|
* a method parameter.
|
|
* <p>
|
|
* Stable functions and collections make reasonable efforts to provide
|
|
* {@link Object#toString()} operations that do not trigger evaluation
|
|
* of the internal stable values when called.
|
|
* Stable collections have {@link Object#equals(Object)} operations that try
|
|
* to minimize evaluation of the internal stable values when called.
|
|
* <p>
|
|
* As objects can be set via stable values but never removed, this can be a
|
|
* source of unintended memory leaks. A stable value's contents are
|
|
* {@linkplain java.lang.ref##reachability strongly reachable}.
|
|
* Be advised that reachable stable values will hold their set contents until
|
|
* the stable value itself is collected.
|
|
* <p>
|
|
* A {@code StableValue} that has a type parameter {@code T} that is an array
|
|
* type (of arbitrary rank) will only allow the JVM to treat the
|
|
* <em>array reference</em> as a stable value but <em>not its components</em>.
|
|
* Instead, a {@linkplain #list(int, IntFunction) a stable list} of arbitrary
|
|
* depth can be used, which provides stable components. More generally, a
|
|
* stable value can hold other stable values of arbitrary depth and still
|
|
* provide transitive constantness.
|
|
* <p>
|
|
* Stable values, functions, and collections are not {@link Serializable}.
|
|
*
|
|
* @param <T> type of the contents
|
|
*
|
|
* @since 25
|
|
*/
|
|
@PreviewFeature(feature = PreviewFeature.Feature.STABLE_VALUES)
|
|
public sealed interface StableValue<T>
|
|
permits StableValueImpl {
|
|
|
|
/**
|
|
* Tries to set the contents of this StableValue to the provided {@code contents}.
|
|
* The contents of this StableValue can only be set once, implying this method only
|
|
* returns {@code true} once.
|
|
* <p>
|
|
* When this method returns, the contents of this StableValue is always set.
|
|
*
|
|
* @return {@code true} if the contents of this StableValue was set to the
|
|
* provided {@code contents}, {@code false} otherwise
|
|
* @param contents to set
|
|
* @throws IllegalStateException if a supplier invoked by {@link #orElseSet(Supplier)}
|
|
* recursively attempts to set this stable value by calling this method
|
|
* directly or indirectly.
|
|
*/
|
|
boolean trySet(T contents);
|
|
|
|
/**
|
|
* {@return the contents if set, otherwise, returns the provided {@code other} value}
|
|
*
|
|
* @param other to return if the contents is not set
|
|
*/
|
|
T orElse(T other);
|
|
|
|
/**
|
|
* {@return the contents if set, otherwise, throws {@code NoSuchElementException}}
|
|
*
|
|
* @throws NoSuchElementException if no contents is set
|
|
*/
|
|
T orElseThrow();
|
|
|
|
/**
|
|
* {@return {@code true} if the contents is set, {@code false} otherwise}
|
|
*/
|
|
boolean isSet();
|
|
|
|
/**
|
|
* {@return the contents; if unset, first attempts to compute and set the
|
|
* contents using the provided {@code supplier}}
|
|
* <p>
|
|
* The provided {@code supplier} is guaranteed to be invoked at most once if it
|
|
* completes without throwing an exception. If this method is invoked several times
|
|
* with different suppliers, only one of them will be invoked provided it completes
|
|
* without throwing an exception.
|
|
* <p>
|
|
* If the supplier throws an (unchecked) exception, the exception is rethrown and no
|
|
* contents is set. The most common usage is to construct a new object serving
|
|
* as a lazily computed value or memoized result, as in:
|
|
*
|
|
* {@snippet lang=java:
|
|
* Value v = stable.orElseSet(Value::new);
|
|
* }
|
|
* <p>
|
|
* When this method returns successfully, the contents is always set.
|
|
* <p>
|
|
* The provided {@code supplier} will only be invoked once even if invoked from
|
|
* several threads unless the {@code supplier} throws an exception.
|
|
*
|
|
* @param supplier to be used for computing the contents, if not previously set
|
|
* @throws IllegalStateException if the provided {@code supplier} recursively
|
|
* attempts to set this stable value.
|
|
*/
|
|
T orElseSet(Supplier<? extends T> supplier);
|
|
|
|
/**
|
|
* Sets the contents of this StableValue to the provided {@code contents}, or, if
|
|
* already set, throws {@code IllegalStateException}.
|
|
* <p>
|
|
* When this method returns (or throws an exception), the contents is always set.
|
|
*
|
|
* @param contents to set
|
|
* @throws IllegalStateException if the contents was already set
|
|
* @throws IllegalStateException if a supplier invoked by {@link #orElseSet(Supplier)}
|
|
* recursively attempts to set this stable value by calling this method
|
|
* directly or indirectly.
|
|
*/
|
|
void setOrThrow(T contents);
|
|
|
|
// Object methods
|
|
|
|
/**
|
|
* {@return {@code true} if {@code this == obj}, {@code false} otherwise}
|
|
*
|
|
* @param obj to check for equality
|
|
*/
|
|
boolean equals(Object obj);
|
|
|
|
/**
|
|
* {@return the {@linkplain System#identityHashCode(Object) identity hash code} of
|
|
* {@code this} object}
|
|
*/
|
|
int hashCode();
|
|
|
|
// Factories
|
|
|
|
/**
|
|
* {@return a new unset stable value}
|
|
* <p>
|
|
* An unset stable value has no contents.
|
|
*
|
|
* @param <T> type of the contents
|
|
*/
|
|
static <T> StableValue<T> of() {
|
|
return StableValueImpl.of();
|
|
}
|
|
|
|
/**
|
|
* {@return a new pre-set stable value with the provided {@code contents}}
|
|
*
|
|
* @param contents to set
|
|
* @param <T> type of the contents
|
|
*/
|
|
static <T> StableValue<T> of(T contents) {
|
|
final StableValue<T> stableValue = StableValue.of();
|
|
stableValue.trySet(contents);
|
|
return stableValue;
|
|
}
|
|
|
|
/**
|
|
* {@return a new stable supplier}
|
|
* <p>
|
|
* The returned {@linkplain Supplier supplier} is a caching supplier that records
|
|
* the value of the provided {@code underlying} supplier upon being first accessed via
|
|
* the returned supplier's {@linkplain Supplier#get() get()} method.
|
|
* <p>
|
|
* The provided {@code underlying} supplier is guaranteed to be successfully invoked
|
|
* at most once even in a multi-threaded environment. Competing threads invoking the
|
|
* returned supplier's {@linkplain Supplier#get() get()} method when a value is
|
|
* already under computation will block until a value is computed or an exception is
|
|
* thrown by the computing thread. The competing threads will then observe the newly
|
|
* computed value (if any) and will then never execute the {@code underlying} supplier.
|
|
* <p>
|
|
* If the provided {@code underlying} supplier throws an exception, it is rethrown
|
|
* to the initial caller and no contents is recorded.
|
|
* <p>
|
|
* If the provided {@code underlying} supplier recursively calls the returned
|
|
* supplier, an {@linkplain IllegalStateException} will be thrown.
|
|
*
|
|
* @param underlying supplier used to compute a cached value
|
|
* @param <T> the type of results supplied by the returned supplier
|
|
*/
|
|
static <T> Supplier<T> supplier(Supplier<? extends T> underlying) {
|
|
Objects.requireNonNull(underlying);
|
|
return StableSupplier.of(underlying);
|
|
}
|
|
|
|
/**
|
|
* {@return a new stable {@linkplain IntFunction}}
|
|
* <p>
|
|
* The returned function is a caching function that, for each allowed {@code int}
|
|
* input, records the values of the provided {@code underlying}
|
|
* function upon being first accessed via the returned function's
|
|
* {@linkplain IntFunction#apply(int) apply()} method. If the returned function is
|
|
* invoked with an input that is not in the range {@code [0, size)}, an
|
|
* {@link IllegalArgumentException} will be thrown.
|
|
* <p>
|
|
* The provided {@code underlying} function is guaranteed to be successfully invoked
|
|
* at most once per allowed input, even in a multi-threaded environment. Competing
|
|
* threads invoking the returned function's
|
|
* {@linkplain IntFunction#apply(int) apply()} method when a value is already under
|
|
* computation will block until a value is computed or an exception is thrown by
|
|
* the computing thread.
|
|
* <p>
|
|
* If invoking the provided {@code underlying} function throws an exception, it is
|
|
* rethrown to the initial caller and no contents is recorded.
|
|
* <p>
|
|
* If the provided {@code underlying} function recursively calls the returned
|
|
* function for the same input, an {@linkplain IllegalStateException} will
|
|
* be thrown.
|
|
*
|
|
* @param size the upper bound of the range {@code [0, size)} indicating
|
|
* the allowed inputs
|
|
* @param underlying {@code IntFunction} used to compute cached values
|
|
* @param <R> the type of results delivered by the returned IntFunction
|
|
* @throws IllegalArgumentException if the provided {@code size} is negative.
|
|
*/
|
|
static <R> IntFunction<R> intFunction(int size,
|
|
IntFunction<? extends R> underlying) {
|
|
StableUtil.assertSizeNonNegative(size);
|
|
Objects.requireNonNull(underlying);
|
|
return StableIntFunction.of(size, underlying);
|
|
}
|
|
|
|
/**
|
|
* {@return a new stable {@linkplain Function}}
|
|
* <p>
|
|
* The returned function is a caching function that, for each allowed
|
|
* input in the given set of {@code inputs}, records the values of the provided
|
|
* {@code underlying} function upon being first accessed via the returned function's
|
|
* {@linkplain Function#apply(Object) apply()} method. If the returned function is
|
|
* invoked with an input that is not in {@code inputs}, an {@link IllegalArgumentException}
|
|
* will be thrown.
|
|
* <p>
|
|
* The provided {@code underlying} function is guaranteed to be successfully invoked
|
|
* at most once per allowed input, even in a multi-threaded environment. Competing
|
|
* threads invoking the returned function's {@linkplain Function#apply(Object) apply()}
|
|
* method when a value is already under computation will block until a value is
|
|
* computed or an exception is thrown by the computing thread.
|
|
* <p>
|
|
* If invoking the provided {@code underlying} function throws an exception, it is
|
|
* rethrown to the initial caller and no contents is recorded.
|
|
* <p>
|
|
* If the provided {@code underlying} function recursively calls the returned
|
|
* function for the same input, an {@linkplain IllegalStateException} will
|
|
* be thrown.
|
|
*
|
|
* @param inputs the set of (non-null) allowed input values
|
|
* @param underlying {@code Function} used to compute cached values
|
|
* @param <T> the type of the input to the returned Function
|
|
* @param <R> the type of results delivered by the returned Function
|
|
* @throws NullPointerException if the provided set of {@code inputs} contains a
|
|
* {@code null} element.
|
|
*/
|
|
static <T, R> Function<T, R> function(Set<? extends T> inputs,
|
|
Function<? super T, ? extends R> underlying) {
|
|
Objects.requireNonNull(inputs);
|
|
// Checking that the Set of inputs does not contain a `null` value is made in the
|
|
// implementing classes.
|
|
Objects.requireNonNull(underlying);
|
|
return inputs instanceof EnumSet<?> && !inputs.isEmpty()
|
|
? StableEnumFunction.of(inputs, underlying)
|
|
: StableFunction.of(inputs, underlying);
|
|
}
|
|
|
|
/**
|
|
* {@return a new stable list with the provided {@code size}}
|
|
* <p>
|
|
* The returned list is an {@linkplain Collection##unmodifiable unmodifiable} list
|
|
* with the provided {@code size}. The list's elements are computed via the
|
|
* provided {@code mapper} when they are first accessed
|
|
* (e.g. via {@linkplain List#get(int) List::get}).
|
|
* <p>
|
|
* The provided {@code mapper} function is guaranteed to be successfully invoked
|
|
* at most once per list index, even in a multi-threaded environment. Competing
|
|
* threads accessing an element already under computation will block until an element
|
|
* is computed or an exception is thrown by the computing thread.
|
|
* <p>
|
|
* If invoking the provided {@code mapper} function throws an exception, it
|
|
* is rethrown to the initial caller and no value for the element is recorded.
|
|
* <p>
|
|
* Any {@link List#subList(int, int) subList} or {@link List#reversed()} views
|
|
* of the returned list are also stable.
|
|
* <p>
|
|
* The returned list and its {@link List#subList(int, int) subList} or
|
|
* {@link List#reversed()} views implement the {@link RandomAccess} interface.
|
|
* <p>
|
|
* The returned list is unmodifiable and does not implement the
|
|
* {@linkplain Collection##optional-operation optional operations} in the
|
|
* {@linkplain List} interface.
|
|
* <p>
|
|
* If the provided {@code mapper} recursively calls the returned list for the
|
|
* same index, an {@linkplain IllegalStateException} will be thrown.
|
|
*
|
|
* @param size the size of the returned list
|
|
* @param mapper to invoke whenever an element is first accessed
|
|
* (may return {@code null})
|
|
* @param <E> the type of elements in the returned list
|
|
* @throws IllegalArgumentException if the provided {@code size} is negative.
|
|
*/
|
|
static <E> List<E> list(int size,
|
|
IntFunction<? extends E> mapper) {
|
|
StableUtil.assertSizeNonNegative(size);
|
|
Objects.requireNonNull(mapper);
|
|
return SharedSecrets.getJavaUtilCollectionAccess().stableList(size, mapper);
|
|
}
|
|
|
|
/**
|
|
* {@return a new stable map with the provided {@code keys}}
|
|
* <p>
|
|
* The returned map is an {@linkplain Collection##unmodifiable unmodifiable} map whose
|
|
* keys are known at construction. The map's values are computed via the provided
|
|
* {@code mapper} when they are first accessed
|
|
* (e.g. via {@linkplain Map#get(Object) Map::get}).
|
|
* <p>
|
|
* The provided {@code mapper} function is guaranteed to be successfully invoked
|
|
* at most once per key, even in a multi-threaded environment. Competing
|
|
* threads accessing a value already under computation will block until an element
|
|
* is computed or an exception is thrown by the computing thread.
|
|
* <p>
|
|
* If invoking the provided {@code mapper} function throws an exception, it
|
|
* is rethrown to the initial caller and no value associated with the provided key
|
|
* is recorded.
|
|
* <p>
|
|
* Any {@link Map#values()} or {@link Map#entrySet()} views of the returned map are
|
|
* also stable.
|
|
* <p>
|
|
* The returned map is unmodifiable and does not implement the
|
|
* {@linkplain Collection##optional-operations optional operations} in the
|
|
* {@linkplain Map} interface.
|
|
* <p>
|
|
* If the provided {@code mapper} recursively calls the returned map for
|
|
* the same key, an {@linkplain IllegalStateException} will be thrown.
|
|
*
|
|
* @param keys the (non-null) keys in the returned map
|
|
* @param mapper to invoke whenever an associated value is first accessed
|
|
* (may return {@code null})
|
|
* @param <K> the type of keys maintained by the returned map
|
|
* @param <V> the type of mapped values in the returned map
|
|
* @throws NullPointerException if the provided set of {@code inputs} contains a
|
|
* {@code null} element.
|
|
*/
|
|
static <K, V> Map<K, V> map(Set<K> keys,
|
|
Function<? super K, ? extends V> mapper) {
|
|
Objects.requireNonNull(keys);
|
|
// Checking that the Set of keys does not contain a `null` value is made in the
|
|
// implementing class.
|
|
Objects.requireNonNull(mapper);
|
|
return SharedSecrets.getJavaUtilCollectionAccess().stableMap(keys, mapper);
|
|
}
|
|
|
|
}
|