Class ScopedValue.Carrier

java.lang.Object

java.lang.ScopedValue.Carrier

Enclosing class:: ScopedValue<T>

public static final class ScopedValue.Carrier extends Object

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

A Carrier is used to accumulate mappings so that an operation (a Runnable or ScopedValue.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:: 25

Method Summary

Modifier and Type	Method	Description
`<R, X extends Throwable> R`	`call(ScopedValue.CallableOp<? extends R, X> op)`	Calls a value-returning operation with each scoped value in this mapping bound to its value in the current thread.
`<T> T`	`get(ScopedValue<T> key)`	Returns the value of a `ScopedValue` in this mapping.
`void`	`run(Runnable op)`	Runs an operation with each scoped value in this mapping bound to its value in the current thread.
`<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`.

Methods declared in class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Modifier and Type	Method	Description
`protected Object`	`clone()`	Creates and returns a copy of this object.
`boolean`	`equals(Object obj)`	Indicates whether some other object is "equal to" this one.
`protected void`	`finalize()`	Deprecated, for removal: This API element is subject to removal in a future version. Finalization is deprecated and subject to removal in a future release.
`final Class<?>`	`getClass()`	Returns the runtime class of this `Object`.
`int`	`hashCode()`	Returns a hash code value for this object.
`final void`	`notify()`	Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()`	Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()`	Returns a string representation of the object.
`final void`	`wait()`	Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
`final void`	`wait(long timeoutMillis)`	Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait(long timeoutMillis, int nanos)`	Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

Method Details

where

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.

Type Parameters:: T - the type of the value
Parameters:: key - the ScopedValue key; value - the value, can be null
Returns:: a new Carrier with the mappings from this carrier plus the new mapping

get

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

Returns the value of a ScopedValue in this mapping.

Type Parameters:: T - the type of the value
Parameters:: key - the ScopedValue key
Returns:: the value
Throws:: NoSuchElementException - if the key is not present in this mapping

call

public <R, X extends Throwable> R call(ScopedValue.CallableOp<? extends R, X> op) throws 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.

Scoped values are intended to be used in a structured manner. If code invoked directly or indirectly by the operation creates a StructuredTaskScope^PREVIEW but does not close^PREVIEW 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^PREVIEW is thrown.

Type Parameters:: R - the type of the result of the operation; X - type of the exception thrown by the operation
Parameters:: op - the operation to run
Returns:: the result
Throws:: StructureViolationException^PREVIEW - if a structure violation is detected; X - if op completes with an exception

run

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 - the operation to run
Throws:: StructureViolationException^PREVIEW - if a structure violation is detected

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.