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

Class ExtentLocal<T>

java.lang.Object
jdk.incubator.concurrent.ExtentLocal<T>
Type Parameters:
T - the extent local's type
public final class ExtentLocal<T> extends Object
Represents a variable that is local to an extent. It is a per-thread variable that allows context to be set in a caller and read by callees. The extent is the set of methods that the caller directly invokes, and any methods invoked transitively. Extent-local variables also provide a way to share immutable data across threads.

An extent-local variable is bound, meaning it gets a value, when invoking an operation with the Carrier.run or Carrier.call methods. Carrier instances are created by the static method where(ExtentLocal, Object). The operations executed by the run and call methods use the get() method to read the value of a bound extent local. An extent-local variable reverts to being unbound (or its previous value) when the operation completes.

An ExtentLocal object will typically be declared in a private static final field so that it can only be accessed by code in that class (or other classes within its nest).

ExtentLocal bindings are immutable: there is no "set" method. There may be cases when an operation might need to use the same extent-local variable to communicate a different value to the methods that it calls. The requirement is not to change the original binding but to establish a new binding for nested calls. If an extent local already has a value, then run or call methods may be invoked to run another operation with a newly-bound value. Code executed by the operation will read the new value of the extent local. The extent local reverts to its previous value when the operation completes.

Sharing extent-local variables across threads

Extent-local variables can be shared across threads when used in conjunction with StructuredTaskScope. Creating a StructuredTaskScope captures the current thread's extent-local bindings for inheritance by threads forked in the task scope. This means that a thread may bind an extent-local variable and share its value in a structured concurrency context. Threads forked in the task scope that read the extent-local variable will read the value bound by the thread that created the task scope.

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

API Note:
The following example uses an extent local to make credentials available to callees. 
  private static final ExtentLocal<Credentials> CREDENTIALS = ExtentLocal.newInstance();

  Credentials creds = ...
  ExtentLocal.where(CREDENTIALS, creds).run(() -> {
      ...
      Connection connection = connectDatabase();
      ...
  });

  ...

  Connection connectDatabase() {
      Credentials credentials = CREDENTIALS.get();
      ...
  }
Implementation Note:
Extent-local variables are designed to be used in fairly small numbers. get() initially performs a search through enclosing scopes to find an extent-local variable's innermost binding. It then caches the result of the search in a small thread-local cache. Subsequent invocations of get() for that extent local will almost always be very fast. However, if a program has many extent-local variables that it uses cyclically, the cache hit rate will be low and performance will be poor. This design allows extent-local inheritance by StructuredTaskScope threads to be very fast: in essence, no more than copying a pointer, and leaving an extent-local binding also requires little more than updating a pointer.

Because the extent-local per-thread cache is small, you should try to minimize the number of bound extent-local variables in use. For example, if you need 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 extent-local variable to an instance of that record.

For this incubator release, we have provided some system properties to tune the performance of extent-local variables.

The system property jdk.incubator.concurrent.ExtentLocal.cacheSize controls the size of the (per-thread) extent-local cache. This cache is crucial for the performance of extent-local variables. 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 extent-local cache size is 16 entries. It may be varied from 2 to 16 entries in size. ExtentLocal.cacheSize must be an integer power of 2.

For example, you could use -Djdk.incubator.concurrent.ExtentLocal.cacheSize=8.

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

Since:
19

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    ExtentLocal.Carrier
    An immutable map of extent-local variables to values.

  • Method Summary

    Modifier and Type
    Method
    Description
    T
    get()
    Returns the current thread's bound value for this extent-local variable.
    boolean
    isBound()
    Returns true if the extent local is bound to a value.
    static <T> ExtentLocal<T>
    newInstance()
    Creates an extent-local variable to refer to a value of type T.
    T
    orElse(T other)
    Returns the value of the extent local if bound, otherwise returns other.
    <X extends Throwable>
    T
    orElseThrow(Supplier<? extends X> exceptionSupplier)
    Returns the value of the extent local if bound, otherwise throws the exception produced by the exception supplying function.
    static <T> ExtentLocal.Carrier
    where(ExtentLocal<T> key, T value)
    Creates a binding for an extent-local variable.
    static <T> void
    where(ExtentLocal<T> key, T value, Runnable op)
    Creates a binding for extent-local variable and runs an operation with that ExtentLocal bound to the value.
    static <T, U> U
    where(ExtentLocal<T> key, T value, Callable<U> op)
    Creates a binding for an extent-local variable and runs a value-returning operation with that ExtentLocal bound to the value.

    Methods declared in class java.lang.Object

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

  • Method Details

    • where

      public static <T> ExtentLocal.Carrier where(ExtentLocal<T> key, T value)
      Creates a binding for an extent-local variable. The Carrier may be used later to invoke a Callable or Runnable instance. More bindings may be added to the Carrier by further calls to this method.
      Type Parameters:
      T - the type of the ExtentLocal
      Parameters:
      key - the ExtentLocal to bind
      value - the value to bind it to, can be null
      Returns:
      A Carrier instance that contains one binding, that of key and value

    • where

      public static <T, U> U where(ExtentLocal<T> key, T value, Callable<U> op) throws Exception
      Creates a binding for an extent-local variable and runs a value-returning operation with that ExtentLocal bound to the value.
      Type Parameters:
      T - the type of the ExtentLocal
      U - the type of the Result
      Parameters:
      key - the ExtentLocal to bind
      value - the value to bind it to, can be null
      op - the operation to call
      Returns:
      the result
      Throws:
      Exception - if the operation completes with an exception

    • where

      public static <T> void where(ExtentLocal<T> key, T value, Runnable op)
      Creates a binding for extent-local variable and runs an operation with that ExtentLocal bound to the value.
      Type Parameters:
      T - the type of the ExtentLocal
      Parameters:
      key - the ExtentLocal to bind
      value - the value to bind it to, can be null
      op - the operation to run

    • newInstance

      public static <T> ExtentLocal<T> newInstance()
      Creates an extent-local variable to refer to a value of type T.
      Type Parameters:
      T - the type of the extent local's value.
      Returns:
      an extent-local variable

    • get

      public T get()
      Returns the current thread's bound value for this extent-local variable.
      Returns:
      the value of the extent local
      Throws:
      NoSuchElementException - if the extent local is not bound

    • isBound

      public boolean isBound()
      Returns true if the extent local is bound to a value.
      Returns:
      true if the extent local is bound to a value

    • orElse

      public T orElse(T other)
      Returns the value of the extent local if bound, otherwise returns other.
      Parameters:
      other - the value to return if not bound, can be null
      Returns:
      the value of the extent local if bound, otherwise other

    • orElseThrow

      public <X extends Throwable> T orElseThrow(Supplier<? extends X> exceptionSupplier) throws X
      Returns the value of the extent local if bound, otherwise throws the exception produced by the exception supplying function.
      Type Parameters:
      X - Type of the exception to be thrown
      Parameters:
      exceptionSupplier - the supplying function that produces the exception to throw
      Returns:
      the value of the extent local if bound
      Throws:
      X - prodouced by the exception suppying function if the extent local is unbound