Module jdk.incubator.concurrent
Package jdk.incubator.concurrent

Class ScopedValue.Carrier

java.lang.Object
jdk.incubator.concurrent.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 accumlate mappings so that an operation (a Runnable or Callable) 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:
20

  • 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> R call(Callable<? extends R> op) throws Exception
      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.

      Scoped values are intended to be used in a structured manner. If op creates a StructuredTaskScope but does not close it, then exiting op causes the underlying construct of each StructuredTaskScope created in the dynamic scope to be closed. This may require blocking until all child threads have completed their sub-tasks. The closing is done in the reverse order that they were created. Once closed, StructureViolationException is thrown.

      Type Parameters:
      R - the type of the result of the operation
      Parameters:
      op - the operation to run
      Returns:
      the result
      Throws:
      Exception - if op completes with an exception
      See Also:

    • 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.

      Scoped values are intended to be used in a structured manner. If op creates a StructuredTaskScope but does not close it, then exiting op causes the underlying construct of each StructuredTaskScope created in the dynamic scope to be closed. This may require blocking until all child threads have completed their sub-tasks. The closing is done in the reverse order that they were created. Once closed, StructureViolationException is thrown.

      Parameters:
      op - the operation to run
      See Also: