Package io.servicetalk.concurrent.api

Class AsyncContext

java.lang.Object
io.servicetalk.concurrent.api.AsyncContext
public final class AsyncContext extends Object
Presents a static interface to retain state in an asynchronous environment.

This should not be used as a "catch all" to avoid designing APIs which accommodate for your needs. This should be used as a last resort (e.g. for low level framework or infrastructure like tasks) because there maybe non-trivial overhead required to maintain this context.

  • Method Details

    • context

      public static ContextMap context()
      Get the current ContextMap.
      Returns:
      the current ContextMap

    • captureContext

      public static CapturedContext captureContext()
      Grab a reference of the current context.
      Returns:
      the current context.

    • put

      @Nullable public static <T> T put(ContextMap.Key<T> key, @Nullable T value)
      Convenience method to put a new entry to the current context.
      Type Parameters:
      T - The type of object associated with key.
      Parameters:
      key - The ContextMap.Key used to index the value.
      value - the value to put.
      Returns:
      The previous value associated with the key, or null if there was none. null can also indicate the value associated with key is null (if null values are supported by the implementation).
      Throws:
      NullPointerException - (optional behavior) if key or value is null and the underlying ContextMap implementation doesn't support null keys or values.
      UnsupportedOperationException - if this method is not supported by the underlying ContextMap implementation.
      See Also:

    • putIfAbsent

      @Nullable public static <T> T putIfAbsent(ContextMap.Key<T> key, @Nullable T value)
      Convenience method to put a new entry to the current context if this map does not already contain this key or is mapped to null.
      Type Parameters:
      T - The type of object associated with key.
      Parameters:
      key - The ContextMap.Key used to index the value.
      value - the value to put.
      Returns:
      The previous value associated with the key, or null if there was none. null can also indicate the value associated with key is null (if null values are supported by the implementation).
      Throws:
      NullPointerException - (optional behavior) if key or value is null and the underlying ContextMap implementation doesn't support null keys or values.
      UnsupportedOperationException - if this method is not supported by the underlying ContextMap implementation.
      See Also:

    • computeIfAbsent

      @Nullable public static <T> T computeIfAbsent(ContextMap.Key<T> key, Function<ContextMap.Key<T>,T> computeFunction)
      Convenience method to compute a new entry for the current context if this map does not already contain this key or is mapped to null.
      Type Parameters:
      T - The type of object associated with key.
      Parameters:
      key - The ContextMap.Key used to index the value.
      computeFunction - The function to compute a new value. Implementation may invoke this function multiple times if concurrent threads attempt modifying this context map, result is expected to be idempotent.
      Returns:
      The previous value associated with the key, or null if there was none. null can also indicate the value associated with key is null (if null values are supported by the implementation).
      Throws:
      NullPointerException - (optional behavior) if key or computed value is null and the underlying ContextMap implementation doesn't support null keys or values.
      UnsupportedOperationException - if this method is not supported by the underlying ContextMap implementation.
      See Also:

    • putAll

      public static void putAll(ContextMap map)
      Convenience method to put all the entries into the current context from another ContextMap.
      Parameters:
      map - contains the entries that will be added.
      Throws:
      ConcurrentModificationException - done on a best effort basis if the passed map is detected to be modified while attempting to put all entries.
      NullPointerException - (optional behavior) if any of the map entries has a null key or value and the underlying ContextMap implementation doesn't support null keys or values.
      UnsupportedOperationException - if this method is not supported by the underlying ContextMap implementation.
      See Also:

    • putAll

      public static void putAll(Map<ContextMap.Key<?>,Object> map)
      Convenience method to put all the entries into the current context.
      Parameters:
      map - contains the entries that will be added.
      Throws:
      ConcurrentModificationException - done on a best effort basis if the passed map is detected to be modified while attempting to put all entries.
      NullPointerException - (optional behavior) if any of the map entries has a null key or value and the underlying ContextMap implementation doesn't support null keys or values.
      UnsupportedOperationException - if this method is not supported by the underlying ContextMap implementation.
      See Also:

    • putAllFromMap

      @Deprecated public static void putAllFromMap(Map<ContextMap.Key<?>,Object> map)
      Deprecated.
      Use putAll(Map)
      Convenience method to put all the entries into the current context.
      Parameters:
      map - contains the entries that will be added.
      Throws:
      ConcurrentModificationException - done on a best effort basis if the passed map is detected to be modified while attempting to put all entries.
      NullPointerException - (optional behavior) if any of the map entries has a null key or value and the underlying ContextMap implementation doesn't support null keys or values.
      UnsupportedOperationException - if this method is not supported by the underlying ContextMap implementation.
      See Also:

    • remove

      @Nullable public static <T> T remove(ContextMap.Key<T> key)
      Convenience method to remove an entry from the current context.
      Type Parameters:
      T - The type of object associated with key.
      Parameters:
      key - The ContextMap.Key which identifies an entry for removal.
      Returns:
      the previous value associated with key, or null if there was none. A null value may also indicate there was a previous value which was null.
      Throws:
      NullPointerException - (optional behavior) if key is null and the underlying ContextMap implementation doesn't support null keys or values.
      UnsupportedOperationException - if this method is not supported by the underlying ContextMap implementation.
      See Also:

    • removeAll

      public static boolean removeAll(Iterable<ContextMap.Key<?>> keys)
      Convenience method to remove all entries from the current context associated with the keys from the passed Iterable.
      Parameters:
      keys - The ContextMap.Keys that identify entries for removal.
      Returns:
      true if this map has changed as a result of this operation.
      Throws:
      NullPointerException - (optional behavior) if any of the keys is null and the underlying ContextMap implementation doesn't support null keys.
      UnsupportedOperationException - if this method is not supported by the underlying ContextMap implementation.
      See Also:

    • removeAllEntries

      @Deprecated public static boolean removeAllEntries(Iterable<ContextMap.Key<?>> keys)
      Deprecated.
      Use removeAll(Iterable)
      Convenience method to remove all entries from the current context associated with the keys from the passed Iterable.
      Parameters:
      keys - The ContextMap.Keys that identify entries for removal.
      Returns:
      true if this map has changed as a result of this operation.
      Throws:
      NullPointerException - (optional behavior) if any of the keys is null and the underlying ContextMap implementation doesn't support null keys.
      UnsupportedOperationException - if this method is not supported by the underlying ContextMap implementation.
      See Also:

    • clear

      public static void clear()
      Convenience method to clear all the entries from the current context.
      Throws:
      UnsupportedOperationException - if this method is not supported by the underlying ContextMap implementation.
      See Also:

    • get

      @Nullable public static <T> T get(ContextMap.Key<T> key)
      Convenience method to get the value associated with the key from the current context.
      Type Parameters:
      T - The anticipated type of object associated with key.
      Parameters:
      key - The ContextMap.Key to lookup.
      Returns:
      the value associated with the key, or null if no value is associated. null can also indicate the value associated with key is null (if null values are supported by the underlying ContextMap implementation).
      Throws:
      NullPointerException - (optional behavior) if key is null and the underlying ContextMap implementation doesn't support null keys or values.
      See Also:

    • getOrDefault

      @Nullable public static <T> T getOrDefault(ContextMap.Key<T> key, T defaultValue)
      Convenience method to get the value associated with key from the current context, or defaultValue if no value is associated.
      Type Parameters:
      T - The anticipated type of object associated with key.
      Parameters:
      key - The ContextMap.Key to lookup.
      defaultValue - The value to return if no value is associated with the key.
      Returns:
      The value associated with the key (can return null if null values are supported by the underlying ContextMap implementation), or defaultValue if no value is associated.
      Throws:
      NullPointerException - (optional behavior) if key is null and the underlying ContextMap implementation doesn't support null keys or values.
      See Also:

    • containsKey

      public static boolean containsKey(ContextMap.Key<?> key)
      Convenience method to determine if the current context contains an entry corresponding to the key.
      Parameters:
      key - The ContextMap.Key to lookup.
      Returns:
      true if the current context contains an entry corresponding to the key, false otherwise.
      Throws:
      NullPointerException - (optional behavior) if key is null and the underlying ContextMap implementation doesn't support null keys.
      See Also:

    • containsValue

      public static boolean containsValue(Object value)
      Convenience method to determine if the current context contains an entry with the specified value.
      Parameters:
      value - the value to lookup.
      Returns:
      true if this context contains one or more entries with the specified value, false otherwise.
      Throws:
      NullPointerException - (optional behavior) if value is null and the underlying ContextMap implementation doesn't support null values.
      See Also:

    • contains

      public static <T> boolean contains(ContextMap.Key<T> key, @Nullable T value)
      Convenience method to determine if this context contains an entry matching the passed key and value.
      Type Parameters:
      T - The anticipated type of object associated with the key.
      Parameters:
      key - The ContextMap.Key to lookup.
      value - The value to match.
      Returns:
      true if this context contains an entry matching the passed key and value, false otherwise.
      Throws:
      NullPointerException - (optional behavior) if key or value is null and the underlying ContextMap implementation doesn't support null keys or values.

    • size

      public static int size()
      Convenience method to determine the number of entries in the current context.
      Returns:
      the number of entries in the current context.
      See Also:

    • isEmpty

      public static boolean isEmpty()
      Convenience method to determine if there are no entries in the current context.
      Returns:
      true if there are no entries in the current context.
      See Also:

    • forEach

      @Nullable public static ContextMap.Key<?> forEach(BiPredicate<ContextMap.Key<?>,Object> consumer)
      Convenience method to iterate over the entries contained in the current context.
      Parameters:
      consumer - Each entry will be passed as key and value arguments to this BiPredicate. A consumer predicate should return true if it wants to keep iterating or false to stop iteration at the current entry.
      Returns:
      null if consumer iterated through all entries or the ContextMap.Key at which the iteration stopped.
      Throws:
      NullPointerException - if consumer is null.
      See Also:

    • forEachEntry

      @Deprecated @Nullable public static ContextMap.Key<?> forEachEntry(BiPredicate<ContextMap.Key<?>,Object> consumer)
      Deprecated.
      Use forEach(BiPredicate)
      Convenience method to iterate over the entries contained in the current context.
      Parameters:
      consumer - Each entry will be passed as key and value arguments to this BiPredicate. A consumer predicate should return true if it wants to keep iterating or false to stop iteration at the current entry.
      Returns:
      null if consumer iterated through all entries or the ContextMap.Key at which the iteration stopped.
      Throws:
      NullPointerException - if consumer is null.
      See Also:

    • wrapJdkExecutor

      public static Executor wrapJdkExecutor(Executor executor)
      Wrap an Executor to ensure it is able to track AsyncContext correctly.
      Parameters:
      executor - The executor to wrap.
      Returns:
      The wrapped executor.

    • wrapExecutor

      public static Executor wrapExecutor(Executor executor)
      Wrap an Executor to ensure it is able to track AsyncContext correctly.
      Parameters:
      executor - The executor to wrap.
      Returns:
      The wrapped executor.

    • wrapJdkExecutorService

      public static ExecutorService wrapJdkExecutorService(ExecutorService executor)
      Wrap an ExecutorService to ensure it is able to track AsyncContext correctly.
      Parameters:
      executor - The executor to wrap.
      Returns:
      The wrapped executor.

    • wrapJdkScheduledExecutorService

      public static ScheduledExecutorService wrapJdkScheduledExecutorService(ScheduledExecutorService executor)
      Wrap a ScheduledExecutorService to ensure it is able to track AsyncContext correctly.
      Parameters:
      executor - The executor to wrap.
      Returns:
      The wrapped executor.

    • wrapRunnable

      public static Runnable wrapRunnable(Runnable runnable)
      Wrap a Runnable to ensure it is able to track AsyncContext correctly.
      Parameters:
      runnable - The runnable to wrap.
      Returns:
      The wrapped Runnable.

    • wrapCallable

      public static <V> Callable<V> wrapCallable(Callable<V> callable)
      Wrap a Callable to ensure it is able to track AsyncContext correctly.
      Type Parameters:
      V - The type of data returned by callable.
      Parameters:
      callable - The callable to wrap.
      Returns:
      The wrapped Callable.

    • wrapConsumer

      public static <T> Consumer<T> wrapConsumer(Consumer<T> consumer)
      Wrap a Consumer to ensure it is able to track AsyncContext correctly.
      Type Parameters:
      T - The type of data consumed by consumer.
      Parameters:
      consumer - The consumer to wrap.
      Returns:
      The wrapped Consumer.

    • wrapFunction

      public static <T, U> Function<T,U> wrapFunction(Function<T,U> func)
      Wrap a Function to ensure it is able to track AsyncContext correctly.
      Type Parameters:
      T - The type of data consumed by func.
      U - The type of data returned by func.
      Parameters:
      func - The function to wrap.
      Returns:
      The wrapped Function.

    • wrapBiConsume

      public static <T, U> BiConsumer<T,U> wrapBiConsume(BiConsumer<T,U> consumer)
      Wrap a BiFunction to ensure it is able to track AsyncContext correctly.
      Type Parameters:
      T - The type of data consumed by func.
      U - The type of data consumed by func.
      Parameters:
      consumer - The consumer to wrap.
      Returns:
      The wrapped BiConsumer.

    • wrapBiFunction

      public static <T, U, V> BiFunction<T,U,V> wrapBiFunction(BiFunction<T,U,V> func)
      Wrap a BiFunction to ensure it is able to track AsyncContext correctly.
      Type Parameters:
      T - The type of data consumed by func.
      U - The type of data consumed by func.
      V - The type of data returned by func.
      Parameters:
      func - The function to wrap.
      Returns:
      The wrapped BiFunction.

    • disable

      public static void disable()
      Disable AsyncContext. It is assumed the application will call this in a well orchestrated fashion. For example the behavior of in flight AsyncContext is undefined, objects that are already initialized with AsyncContext enabled may continue to preserve AsyncContext in an unreliable fashion. and also how this behaves relative to concurrent invocation is undefined. External synchronization should be used to ensure this change is visible to other threads.

    • isDisabled

      public static boolean isDisabled()
      Determine if disable() has been previously called.
      Returns:
      true if disable() has been previously called.