A value that may be safely and efficiently shared to methods without using method parameters.

In the Java programming language, data is usually passed to a method by means of a method parameter. The data may need to be passed through a sequence of many methods to get to the method that makes use of the data. Every method in the sequence of calls needs to declare the parameter and every method has access to the data. ScopedValue provides a means to pass data to a faraway method (typically a callback) without using method parameters. In effect, a ScopedValue is an implicit method parameter. It is "as if" every method in a sequence of calls has an additional parameter. None of the methods declare the parameter and only the methods that have access to the ScopedValue object can access its value (the data). ScopedValue makes it possible to securely pass data from a caller to a faraway callee through a sequence of intermediate methods that do not declare a parameter for the data and have no access to the data.

The ScopedValue API works by executing a method with a ScopedValue object bound to some value for the bounded period of execution of a method. The method may invoke another method, which in turn may invoke another. The unfolding execution of the methods define a dynamic scope. Code in these methods with access to the ScopedValue object may read its value. The ScopedValue object reverts to being unbound when the original method completes normally or with an exception. The ScopedValue API supports executing a Runnable, or CallableOp with a ScopedValue bound to a value.

Consider the following example with a scoped value "NAME" bound to the value "duke" for the execution of a Runnable's run method. The run method, in turn, invokes a method doSomething.

private static final ScopedValue<String> NAME = ScopedValue.newInstance();

ScopedValue.runWhere(NAME, "duke", () -> doSomething());

Code executed directly or indirectly by doSomething, with access to the field NAME, can invoke NAME.get() to read the value "duke". NAME is bound while executing the run method. It reverts to being unbound when the run method completes.

The example using runWhere invokes a method that does not return a result. The callWhere method can be used to invoke a method that returns a result. In addition, ScopedValue defines the where(ScopedValue, Object) method for cases where multiple mappings (of ScopedValue to value) are accumulated in advance of calling a method with all ScopedValues bound to their value.

Bindings are per-thread

A ScopedValue binding to a value is per-thread. Invoking xxxWhere executes a method with a ScopedValue bound to a value for the current thread. The get method returns the value bound for the current thread.

In the example, if code executed by one thread invokes this:

ScopedValue.runWhere(NAME, "duke1", () -> doSomething());

and code executed by another thread invokes:

ScopedValue.runWhere(NAME, "duke2", () -> doSomething());

then code in doSomething (or any method that it calls) invoking NAME.get() will read the value "duke1" or "duke2", depending on which thread is executing.

Scoped values as capabilities

A ScopedValue object should be treated as a capability or a key to access its value when the ScopedValue is bound. Secure usage depends on access control (see The Java Virtual Machine Specification, Section 5.4.4) and taking care to not share the ScopedValue object. In many cases, a ScopedValue will be declared in a final and static field so that it is only accessible to code in a single class (or nest).

Rebinding

The ScopedValue API allows a new binding to be established for nested dynamic scopes. This is known as rebinding. A ScopedValue that is bound to a value may be bound to a new value for the bounded execution of a new method. The unfolding execution of code executed by that method defines the nested dynamic scope. When the method completes, the value of the ScopedValue reverts to its previous value.

In the above example, suppose that code executed by doSomething binds NAME to a new value with:

ScopedValue.runWhere(NAME, "duchess", () -> doMore());

Code executed directly or indirectly by doMore() that invokes NAME.get() will read the value "duchess". When doMore() completes then the value of NAME reverts to "duke".

Inheritance

ScopedValue supports sharing across threads. This sharing is limited to structured cases where child threads are started and terminate within the bounded period of execution by a parent thread. When using a StructuredTaskScope, scoped value bindings are captured when creating a StructuredTaskScope and inherited by all threads started in that task scope with the fork method.

A ScopedValue that is shared across threads requires that the value be an immutable object or for all access to the value to be appropriately synchronized.

In the following example, the ScopedValue NAME is bound to the value "duke" for the execution of a runnable operation. The code in the run method creates a StructuredTaskScope that forks three tasks. Code executed directly or indirectly by these threads running childTask1(), childTask2(), and childTask3() that invokes NAME.get() will read the value "duke".

private static final ScopedValue<String> NAME = ScopedValue.newInstance();

ScopedValue.runWhere(NAME, "duke", () -> {
    try (var scope = new StructuredTaskScope<String>()) {

        scope.fork(() -> childTask1());
        scope.fork(() -> childTask2());
        scope.fork(() -> childTask3());

        ...
     }
});

Unless otherwise specified, passing a null argument to a method in this class will cause a NullPointerException to be thrown.

Implementation Note

Scoped values are designed to be used in fairly small numbers. get initially performs a search through enclosing scopes to find a scoped value's innermost binding. It then caches the result of the search in a small thread-local cache. Subsequent invocations of get for that scoped value will almost always be very fast. However, if a program has many scoped values that it uses cyclically, the cache hit rate will be low and performance will be poor. This design allows scoped-value inheritance by StructuredTaskScope threads to be very fast: in essence, no more than copying a pointer, and leaving a scoped-value binding also requires little more than updating a pointer.

Because the scoped-value per-thread cache is small, clients should minimize the number of bound scoped values in use. For example, if it is necessary to pass a number of values in this way, it makes sense to create a record class to hold those values, and then bind a single ScopedValue to an instance of that record.

For this release, the reference implementation provides some system properties to tune the performance of scoped values.

The system property java.lang.ScopedValue.cacheSize controls the size of the (per-thread) scoped-value cache. This cache is crucial for the performance of scoped values. If it is too small, the runtime library will repeatedly need to scan for each get. If it is too large, memory will be unnecessarily consumed. The default scoped-value cache size is 16 entries. It may be varied from 2 to 16 entries in size. ScopedValue.cacheSize must be an integer power of 2.

For example, you could use -Djava.lang.ScopedValue.cacheSize=8.

The other system property is jdk.preserveScopedValueCache. This property determines whether the per-thread scoped-value cache is preserved when a virtual thread is blocked. By default this property is set to true, meaning that every virtual thread preserves its scoped-value cache when blocked. Like ScopedValue.cacheSize, this is a space versus speed trade-off: in situations where many virtual threads are blocked most of the time, setting this property to false might result in a useful memory saving, but each virtual thread's scoped-value cache would have to be regenerated after a blocking operation.

Modifier and Type	Class and Description
private static class	ScopedValue.Cache
public static interface	ScopedValue.CallableOp< result type of the operation T, type of the exception thrown by the operation X extends Throwable> Preview Third Preview of Scoped Values (JEP 481). An operation that returns a result and may throw an exception.
public static class	ScopedValue.Carrier Preview Third Preview of Scoped Values (JEP 481). A mapping of scoped values, as keys, to values.
pack-priv static class	ScopedValue.Snapshot An immutable map from `ScopedValue` to values.

Modifier and Type	Field and Description
private final int	hash
private static final Object	NEW_THREAD_BINDINGS
private static int	nextKey

Access	Constructor and Description
private	ScopedValue()

Method Summary

Modifier and Type	Method and Description
pack-priv int	Returns: the bitmask bitmask() Return a bit mask that may be used to determine if this ScopedValue is bound in the current context.
public static < the type of the value T, the result type R, type of the exception thrown by the operation X extends Throwable> R	Returns: the result callWhere(ScopedValue<T> the `ScopedValue` key key, T the value, can be `null` value, ScopedValue.CallableOp<? extends R, X> the operation to call op) Calls a value-returning operation with a `ScopedValue` bound to a value in the current thread.
pack-priv static boolean	containsAll(int bitmask, int targetBits)
private Object	findBinding() Return the value of the scoped value or NIL if not bound.
private static synchronized int	generateKey()
public T	Returns: the value of the scoped value if bound in the current thread get() Returns the value of the scoped value if bound in the current thread.
public int	hashCode() Overrides java.lang.Object.hashCode. Returns a hash code value for this object.
public boolean	Returns: `true` if this scoped value is bound in the current thread isBound() Returns `true` if this scoped value is bound in the current thread.
public static < the type of the value T> ScopedValue<T>	Returns: a new `ScopedValue` newInstance() Creates a scoped value that is initially unbound for all threads.
public T	Returns: the value of the scoped value if bound, otherwise `other` orElse(T the value to return if not bound, can be `null` other) Returns the value of this scoped value if bound in the current thread, otherwise returns `other`.
public < the type of the exception that may be thrown X extends Throwable> T	Returns: the value of the scoped value if bound in the current thread orElseThrow(Supplier<? extends X> the supplying function that produces the exception to throw exceptionSupplier) Returns the value of this scoped value if bound in the current thread, otherwise throws an exception produced by the exception supplying function.
public static < the type of the value T> void	runWhere(ScopedValue<T> the `ScopedValue` key key, T the value, can be `null` value, Runnable the operation to call op) Run an operation with a `ScopedValue` bound to a value in the current thread.
private static ScopedValue.Snapshot	scopedValueBindings()
private static Object[]	scopedValueCache()
private static void	setScopedValueCache(Object[] cache)
private T	slowGet()
public static < the type of the value T> ScopedValue.Carrier	Returns: a new `Carrier` with a single mapping where(ScopedValue<T> the `ScopedValue` key key, T the value, can be `null` value) Creates a new `Carrier` with a single mapping of a `ScopedValue` key to a value.

Inherited from java.lang.Object:: clone equals finalize getClass notify notifyAll toString wait wait wait

hash	back to summary
private final int hash

NEW_THREAD_BINDINGS	back to summary
private static final Object NEW_THREAD_BINDINGS

nextKey	back to summary
private static int nextKey

ScopedValue	back to summary
private ScopedValue()

Method Detail

bitmask	back to summary
pack-priv int bitmask() Return a bit mask that may be used to determine if this ScopedValue is bound in the current context. Each Carrier holds a bit mask which is the OR of all the bit masks of the bound ScopedValues. Returns:int the bitmask

bitmask

back to summary

pack-priv int bitmask()

Return a bit mask that may be used to determine if this ScopedValue is bound in the current context. Each Carrier holds a bit mask which is the OR of all the bit masks of the bound ScopedValues.

Returns:int: the bitmask

callWhere back to summary

callWhere	back to summary
public static <T, R, X extends Throwable> R callWhere(ScopedValue<T> key, T value, ScopedValue.CallableOp<? extends R, X> op) throws CallableOp-:X Calls a value-returning operation with a `ScopedValue` bound to a value in the current thread. When the operation completes (normally or with an exception), the `ScopedValue` will revert to being unbound, or revert to its previous value when previously bound, in the current thread. If `op` completes with an exception then it propagated by this method. Scoped values are intended to be used in a structured manner. If code invoked directly or indirectly by the operation creates a `StructuredTaskScope` but does not close it, then it is detected as a structure violation when the operation completes (normally or with an exception). In that case, the underlying construct of the `StructuredTaskScope` is closed and `StructureViolationException` is thrown. Implementation Note This method is implemented to be equivalent to: `ScopedValue.where(key, value).call(op);` ScopedValue.where(key, value).call(op); Parameters <T> the type of the value <R> the result type <X> type of the exception thrown by the operation key:ScopedValue<T> the `ScopedValue` key value:T the value, can be `null` op:ScopedValue.CallableOp<? extends R, X> the operation to call Returns:R the result Exceptions CallableOp-:X: if the operation completes with an exception StructureViolationException: if a structure violation is detected Since 23

public static <T, R, X extends Throwable> R callWhere(ScopedValue<T> key, T value, ScopedValue.CallableOp<? extends R, X> op) throws CallableOp-:X

Calls a value-returning operation with a ScopedValue bound to a value in the current thread. When the operation completes (normally or with an exception), the ScopedValue will revert to being unbound, or revert to its previous value when previously bound, in the current thread. If op completes with an exception then it propagated by this method.

Scoped values are intended to be used in a structured manner. If code invoked directly or indirectly by the operation creates a StructuredTaskScope but does not close it, then it is detected as a structure violation when the operation completes (normally or with an exception). In that case, the underlying construct of the StructuredTaskScope is closed and StructureViolationException is thrown.

Implementation Note

This method is implemented to be equivalent to:

ScopedValue.where(key, value).call(op);

Parameters

<T>: the type of the value
<R>: the result type
<X>: type of the exception thrown by the operation
key:ScopedValue<T>: the ScopedValue key
value:T: the value, can be null
op:ScopedValue.CallableOp<? extends R, X>: the operation to call

Returns:R

the result

Exceptions

CallableOp-:X:: if the operation completes with an exception
StructureViolationException:: if a structure violation is detected

Since

containsAll	back to summary
pack-priv static boolean containsAll(int bitmask, int targetBits)

findBinding	back to summary
private Object findBinding() Return the value of the scoped value or NIL if not bound.

generateKey	back to summary
private static synchronized int generateKey()

get	back to summary
public T get() Returns the value of the scoped value if bound in the current thread. Returns:T the value of the scoped value if bound in the current thread Annotations @ForceInline @SuppressWarnings:unchecked Exceptions NoSuchElementException: if the scoped value is not bound

get

back to summary

public T get()

Returns the value of the scoped value if bound in the current thread.

Returns:T

the value of the scoped value if bound in the current thread

Annotations

@ForceInline
@SuppressWarnings:unchecked

Exceptions

NoSuchElementException:: if the scoped value is not bound

hashCode back to summary

hashCode	back to summary
public int hashCode() Overrides java.lang.Object.hashCode. Doc from java.lang.Object.hashCode. Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by `java.util.HashMap`. The general contract of `hashCode` is: Whenever it is invoked on the same object more than once during an execution of a Java application, the `hashCode` method must consistently return the same integer, provided no information used in `equals` comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application. If two objects are equal according to the `equals` method, then calling the `hashCode` method on each of the two objects must produce the same integer result. It is not required that if two objects are unequal according to the `equals` method, then calling the `hashCode` method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables. Returns:int a hash code value for this object Annotations @Override

public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.

Returns:int

a hash code value for this object

Annotations

@Override

isBound back to summary

isBound	back to summary
public boolean isBound() Returns `true` if this scoped value is bound in the current thread. Returns:boolean `true` if this scoped value is bound in the current thread

public boolean isBound()

Returns true if this scoped value is bound in the current thread.

Returns:boolean: true if this scoped value is bound in the current thread

newInstance back to summary

newInstance	back to summary
public static <T> ScopedValue<T> newInstance() Creates a scoped value that is initially unbound for all threads. Parameters <T> the type of the value Returns:ScopedValue<T> a new `ScopedValue`

public static <T> ScopedValue<T> newInstance()

Creates a scoped value that is initially unbound for all threads.

Parameters

<T>: the type of the value

Returns:ScopedValue<T>

a new ScopedValue

orElse back to summary

orElse	back to summary
public T orElse(T other) Returns the value of this scoped value if bound in the current thread, otherwise returns `other`. Parameters other:T the value to return if not bound, can be `null` Returns:T the value of the scoped value if bound, otherwise `other`

public T orElse(T other)

Returns the value of this scoped value if bound in the current thread, otherwise returns other.

Parameters

other:T: the value to return if not bound, can be null

Returns:T

the value of the scoped value if bound, otherwise other

orElseThrow	back to summary
public <X extends Throwable> T orElseThrow(Supplier<? extends X> exceptionSupplier) throws Supplier-:X Returns the value of this scoped value if bound in the current thread, otherwise throws an exception produced by the exception supplying function. Parameters <X> the type of the exception that may be thrown exceptionSupplier:Supplier<? extends X> the supplying function that produces the exception to throw Returns:T the value of the scoped value if bound in the current thread Exceptions Supplier-:X: if the scoped value is not bound in the current thread

orElseThrow

back to summary

public <X extends Throwable> T orElseThrow(Supplier<? extends X> exceptionSupplier) throws Supplier-:X

Returns the value of this scoped value if bound in the current thread, otherwise throws an exception produced by the exception supplying function.

Parameters

<X>: the type of the exception that may be thrown
exceptionSupplier:Supplier<? extends X>: the supplying function that produces the exception to throw

Returns:T

the value of the scoped value if bound in the current thread

Exceptions

Supplier-:X:: if the scoped value is not bound in the current thread

runWhere back to summary

runWhere	back to summary
public static <T> void runWhere(ScopedValue<T> key, T value, Runnable op) Run an operation with a `ScopedValue` bound to a value in the current thread. When the operation completes (normally or with an exception), the `ScopedValue` will revert to being unbound, or revert to its previous value when previously bound, in the current thread. If `op` completes with an exception then it propagated by this method. Scoped values are intended to be used in a structured manner. If code invoked directly or indirectly by the operation creates a `StructuredTaskScope` but does not close it, then it is detected as a structure violation when the operation completes (normally or with an exception). In that case, the underlying construct of the `StructuredTaskScope` is closed and `StructureViolationException` is thrown. Implementation Note This method is implemented to be equivalent to: `ScopedValue.where(key, value).run(op);` ScopedValue.where(key, value).run(op); Parameters <T> the type of the value key:ScopedValue<T> the `ScopedValue` key value:T the value, can be `null` op:Runnable the operation to call Exceptions StructureViolationException: if a structure violation is detected

public static <T> void runWhere(ScopedValue<T> key, T value, Runnable op)

Run an operation with a ScopedValue bound to a value in the current thread. When the operation completes (normally or with an exception), the ScopedValue will revert to being unbound, or revert to its previous value when previously bound, in the current thread. If op completes with an exception then it propagated by this method.

Implementation Note

This method is implemented to be equivalent to:

ScopedValue.where(key, value).run(op);

Parameters

<T>: the type of the value
key:ScopedValue<T>: the ScopedValue key
value:T: the value, can be null
op:Runnable: the operation to call

Exceptions

StructureViolationException:: if a structure violation is detected

scopedValueBindings	back to summary
private static ScopedValue.Snapshot scopedValueBindings()

scopedValueCache	back to summary
private static Object[] scopedValueCache()

setScopedValueCache	back to summary
private static void setScopedValueCache(Object[] cache)

slowGet	back to summary
private T slowGet() Annotations @SuppressWarnings:unchecked

where back to summary

where	back to summary
public static <T> ScopedValue.Carrier where(ScopedValue<T> key, T value) Creates a new `Carrier` with a single mapping of a `ScopedValue` key to a value. The `Carrier` can be used to accumulate mappings so that an operation can be executed with all scoped values in the mapping bound to values. The following example runs an operation with `k1` bound (or rebound) to `v1`, and `k2` bound (or rebound) to `v2`. `ScopedValue.where(k1, v1).where(k2, v2).run(() -> ... );` ScopedValue.where(k1, v1).where(k2, v2).run(() -> ... ); Parameters <T> the type of the value key:ScopedValue<T> the `ScopedValue` key value:T the value, can be `null` Returns:ScopedValue.Carrier a new `Carrier` with a single mapping

public static <T> ScopedValue.Carrier where(ScopedValue<T> key, T value)

Creates a new Carrier with a single mapping of a ScopedValue key to a value. The Carrier can be used to accumulate mappings so that an operation can be executed with all scoped values in the mapping bound to values. The following example runs an operation with k1 bound (or rebound) to v1, and k2 bound (or rebound) to v2.

ScopedValue.where(k1, v1).where(k2, v2).run(() -> ... );

Parameters

<T>: the type of the value
key:ScopedValue<T>: the ScopedValue key
value:T: the value, can be null

Returns:ScopedValue.Carrier

a new Carrier with a single mapping

java.lang back to summary

private final Class ScopedValue.Cache

Class Inheritance

extends Object

java.lang.Object
java.lang.ScopedValue.Cache

Field Summary

Modifier and Type	Field and Description
private static final int	CACHE_TABLE_SIZE
pack-priv static final int	INDEX_BITS
private static final int	MAX_CACHE_SIZE
pack-priv static final int	PRIMARY_MASK
private static final int	SLOT_MASK
pack-priv static final int	TABLE_MASK
pack-priv static final int	TABLE_SIZE
private static final JavaUtilConcurrentTLRAccess	THREAD_LOCAL_RANDOM_ACCESS

Constructor Summary

Access	Constructor and Description
private	Cache()

Method Summary

Modifier and Type	Method and Description
private static boolean	chooseVictim()
private static Object	getKey(Object[] objs, int n)
pack-priv static void	invalidate(int toClearBits)
pack-priv static int	primaryIndex(ScopedValue<?> key)
private static int	primarySlot(ScopedValue<?> key)
pack-priv static int	primarySlot(int hash)
pack-priv static void	put(ScopedValue<?> key, Object value)
pack-priv static int	secondaryIndex(ScopedValue<?> key)
private static int	secondarySlot(ScopedValue<?> key)
pack-priv static int	secondarySlot(int hash)
private static void	setKey(Object[] objs, int n, Object key)
private static void	setKeyAndObjectAt(int n, Object key, Object value)
private static void	setKeyAndObjectAt(Object[] cache, int n, Object key, Object value)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

CACHE_TABLE_SIZE	back to summary
private static final int CACHE_TABLE_SIZE

INDEX_BITS	back to summary
pack-priv static final int INDEX_BITS

MAX_CACHE_SIZE	back to summary
private static final int MAX_CACHE_SIZE

PRIMARY_MASK	back to summary
pack-priv static final int PRIMARY_MASK

SLOT_MASK	back to summary
private static final int SLOT_MASK

TABLE_MASK	back to summary
pack-priv static final int TABLE_MASK

TABLE_SIZE	back to summary
pack-priv static final int TABLE_SIZE

THREAD_LOCAL_RANDOM_ACCESS	back to summary
private static final JavaUtilConcurrentTLRAccess THREAD_LOCAL_RANDOM_ACCESS

Constructor Detail

Cache	back to summary
private Cache()

Method Detail

chooseVictim	back to summary
private static boolean chooseVictim()

getKey	back to summary
private static Object getKey(Object[] objs, int n)

invalidate	back to summary
pack-priv static void invalidate(int toClearBits)

primaryIndex	back to summary
pack-priv static int primaryIndex(ScopedValue<?> key)

primarySlot	back to summary
private static int primarySlot(ScopedValue<?> key)

primarySlot	back to summary
pack-priv static int primarySlot(int hash)

put	back to summary
pack-priv static void put(ScopedValue<?> key, Object value)

secondaryIndex	back to summary
pack-priv static int secondaryIndex(ScopedValue<?> key)

secondarySlot	back to summary
private static int secondarySlot(ScopedValue<?> key)

secondarySlot	back to summary
pack-priv static int secondarySlot(int hash)

setKey	back to summary
private static void setKey(Object[] objs, int n, Object key)

setKeyAndObjectAt	back to summary
private static void setKeyAndObjectAt(int n, Object key, Object value)

setKeyAndObjectAt	back to summary
private static void setKeyAndObjectAt(Object[] cache, int n, Object key, Object value)

java.lang back to summary

public final Class ScopedValue.Carrier

Class Inheritance

extends Object

java.lang.Object
java.lang.ScopedValue.Carrier

Annotations

@PreviewFeature
feature:SCOPED_VALUES

Preview

Third Preview of Scoped Values (JEP 481).

Programs can only use Carrier when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.

A mapping of scoped values, as keys, to values.

A Carrier is used to accumulate mappings so that an operation (a Runnable or CallableOp) can be executed with all scoped values in the mapping bound to values. The following example runs an operation with k1 bound (or rebound) to v1, and k2 bound (or rebound) to v2.

ScopedValue.where(k1, v1).where(k2, v2).run(() -> ... );

A Carrier is immutable and thread-safe. The where method returns a new Carrier object, it does not mutate an existing mapping.

Unless otherwise specified, passing a null argument to a method in this class will cause a NullPointerException to be thrown.

Since: 21

Field Summary

Modifier and Type	Field and Description
pack-priv final int	bitmask
pack-priv final ScopedValue<?>	key
pack-priv final ScopedValue.Carrier	prev
pack-priv final Object	value

Constructor Summary

Access	Constructor and Description
pack-priv	Carrier(ScopedValue<?> key, Object value, ScopedValue.Carrier prev)

Method Summary

Modifier and Type	Method and Description
public < the type of the result of the operation R, type of the exception thrown by the operation X extends Throwable> R	Returns: the result call(ScopedValue.CallableOp<? extends R, X> the operation to run op) Calls a value-returning operation with each scoped value in this mapping bound to its value in the current thread.
pack-priv Object	get()
public < the type of the value T> T	Returns: the value get(ScopedValue<T> the `ScopedValue` key key) Returns the value of a `ScopedValue` in this mapping.
pack-priv ScopedValue<?>	getKey()
pack-priv static <T> ScopedValue.Carrier	of(ScopedValue<T> key, T value)
public void	run(Runnable the operation to run op) Runs an operation with each scoped value in this mapping bound to its value in the current thread.
private <R, X extends Throwable> R	runWith(ScopedValue.Snapshot newSnapshot, ScopedValue.CallableOp<R, X> op) Execute the action with a set of ScopedValue bindings.
private void	runWith(ScopedValue.Snapshot newSnapshot, Runnable op) Execute the action with a set of `ScopedValue` bindings.
private static <T> ScopedValue.Carrier	where(ScopedValue<T> key, T value, ScopedValue.Carrier prev) Add a binding to this map, returning a new Carrier instance.
public < the type of the value T> ScopedValue.Carrier	Returns: a new `Carrier` with the mappings from this carrier plus the new mapping where(ScopedValue<T> the `ScopedValue` key key, T the value, can be `null` value) Returns a new `Carrier` with the mappings from this carrier plus a new mapping from `key` to `value`.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

bitmask	back to summary
pack-priv final int bitmask

key	back to summary
pack-priv final ScopedValue<?> key

prev	back to summary
pack-priv final ScopedValue.Carrier prev

value	back to summary
pack-priv final Object value

Constructor Detail

Carrier	back to summary
pack-priv Carrier(ScopedValue<?> key, Object value, ScopedValue.Carrier prev)

Method Detail

call back to summary

public <R, X extends Throwable> R call(ScopedValue.CallableOp<? extends R, X> op) throws CallableOp-:X

Calls a value-returning operation with each scoped value in this mapping bound to its value in the current thread. When the operation completes (normally or with an exception), each scoped value in the mapping will revert to being unbound, or revert to its previous value when previously bound, in the current thread. If op completes with an exception then it propagated by this method.

Parameters

<R>: the type of the result of the operation
<X>: type of the exception thrown by the operation
op:ScopedValue.CallableOp<? extends R, X>: the operation to run

Returns:R

the result

Exceptions

CallableOp-:X:: if op completes with an exception
StructureViolationException:: if a structure violation is detected

Since

get	back to summary
pack-priv Object get()

get back to summary

public <T> T get(ScopedValue<T> key)

Returns the value of a ScopedValue in this mapping.

Parameters

<T>: the type of the value
key:ScopedValue<T>: the ScopedValue key

Returns:T

the value

Annotations

@SuppressWarnings:unchecked

Exceptions

NoSuchElementException:: if the key is not present in this mapping

getKey	back to summary
pack-priv ScopedValue<?> getKey()

of	back to summary
pack-priv static <T> ScopedValue.Carrier of(ScopedValue<T> key, T value)

run back to summary

public void run(Runnable op)

Runs an operation with each scoped value in this mapping bound to its value in the current thread. When the operation completes (normally or with an exception), each scoped value in the mapping will revert to being unbound, or revert to its previous value when previously bound, in the current thread. If op completes with an exception then it propagated by this method.

Parameters

op:Runnable: the operation to run

Exceptions

StructureViolationException:: if a structure violation is detected

runWith

back to summary

private <R, X extends Throwable> R runWith(ScopedValue.Snapshot newSnapshot, ScopedValue.CallableOp<R, X> op)

Execute the action with a set of ScopedValue bindings. The VM recognizes this method as special, so any changes to the name or signature require corresponding changes in JVM_FindScopedValueBindings().

Annotations

@Hidden
@ForceInline

runWith back to summary

private void runWith(ScopedValue.Snapshot newSnapshot, Runnable op)

Execute the action with a set of ScopedValue bindings. The VM recognizes this method as special, so any changes to the name or signature require corresponding changes in JVM_FindScopedValueBindings().

Annotations

@Hidden
@ForceInline

where	back to summary
private static <T> ScopedValue.Carrier where(ScopedValue<T> key, T value, ScopedValue.Carrier prev) Add a binding to this map, returning a new Carrier instance.

where back to summary

public <T> ScopedValue.Carrier where(ScopedValue<T> key, T value)

Returns a new Carrier with the mappings from this carrier plus a new mapping from key to value. If this carrier already has a mapping for the scoped value key then it will map to the new value. The current carrier is immutable, so it is not changed by this method.

Parameters

<T>: the type of the value
key:ScopedValue<T>: the ScopedValue key
value:T: the value, can be null

Returns:ScopedValue.Carrier

a new Carrier with the mappings from this carrier plus the new mapping

public final Class ScopedValue<T>

Bindings are per-thread

Scoped values as capabilities

Rebinding

Inheritance

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private final Class ScopedValue.Cache

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public Interface ScopedValue.CallableOp<T, X extends Throwable>

Method Summary

Method Detail

public final Class ScopedValue.Carrier

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

pack-priv final Class ScopedValue.Snapshot

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

Modifier and Type	Field and Description
pack-priv final ScopedValue.Carrier	bindings
pack-priv final int	bitmask
pack-priv static final ScopedValue.Snapshot	EMPTY_SNAPSHOT
private static final Object	NIL
pack-priv final ScopedValue.Snapshot	prev

Access	Constructor and Description
pack-priv	Snapshot(ScopedValue.Carrier bindings, ScopedValue.Snapshot prev)
protected	Snapshot()