io.grpc:grpc-api 1.60.1 · io.grpc.Context

A context propagation mechanism which can carry scoped-values across API boundaries and between threads. Examples of state propagated via context include:

Security principals and credentials.
Local and distributed tracing information.

A Context object can be attached to the Storage, which effectively forms a scope for the context. The scope is bound to the current thread. Within a scope, its Context is accessible even across API boundaries, through current. The scope is later exited by detaching the Context.

Context objects are immutable and inherit state from their parent. To add or overwrite the current state a new context object must be created and then attached, replacing the previously bound context. For example:

  Context withCredential = Context.current().withValue(CRED_KEY, cred);
  withCredential.run(new Runnable() {
    public void run() {
       readUserRecords(userId, CRED_KEY.get());
    }
  });

Contexts are also used to represent a scoped unit of work. When the unit of work is done the context must be cancelled. This cancellation will cascade to all descendant contexts. You can add a CancellationListener to a context to be notified when it or one of its ancestors has been cancelled. Cancellation does not release the state stored by a context and it's perfectly valid to attach() an already cancelled context to make it current. To cancel a context (and its descendants) you first create a CancellableContext and when you need to signal cancellation call CancellableContext#cancel or CancellableContext#detachAndCancel.

Contexts can also be created with a timeout relative to the system nano clock which will cause it to automatically cancel at the desired time.

Notes and cautions on use:

Every attach() should have a detach() in the same method. And every CancellableContext should be cancelled at some point. Breaking these rules may lead to memory leaks.
While Context objects are immutable they do not place such a restriction on the state they store.
Context is not intended for passing optional parameters to an API and developers should take care to avoid excessive dependence on context when designing an API.
Do not mock this class. Use ROOT for a non-null instance.

Modifier and Type	Class and Description
public static class	Context.CancellableContext A context which inherits cancellation from its parent but which can also be independently cancelled and which will propagate cancellation to its descendants.
public static interface	Context.CancellationListener A listener notified on context cancellation.
pack-priv static @interface	Context.CanIgnoreReturnValue
pack-priv static @interface	Context.CheckReturnValue
private static enum	Context.DirectExecutor
private static class	Context.ExecutableListener Stores listener and executor pair.
public static class	Context.Key<T> Key for indexing values stored in a context.
private static class	Context.LazyStorage
public abstract static class	Context.Storage Defines the mechanisms for attaching and detaching the "current" context.

Modifier and Type	Field and Description
pack-priv final Context.CancellableContext	cancellableAncestor
pack-priv static final int	CONTEXT_DEPTH_WARN_THRESH
pack-priv final int	generation
pack-priv final PersistentHashArrayMappedTrie.Node<Context.Key<?>, Object>	keyValueEntries
pack-priv static final Logger	log
public static final Context	ROOT The logical root context which is the ultimate ancestor of all contexts.

Access	Constructor and Description
private	Context(PersistentHashArrayMappedTrie.Node<Context.Key<?>, Object> keyValueEntries, int generation) Construct a context that cannot be cancelled and will not cascade cancellation from its parent.
private	Context(Context parent, PersistentHashArrayMappedTrie.Node<Context.Key<?>, Object> keyValueEntries) Construct a context that cannot be cancelled but will cascade cancellation from its parent if it is cancellable.
private	Context() Construct for `ROOT`.

Method Summary

Modifier and Type	Method and Description
public void	addListener(final Context.CancellationListener cancellationListener, final Executor executor) Add a listener that will be notified when the context becomes cancelled.
public Context	attach() Attach this context, thus enter a new scope within which this context is `current`.
public <V> V	Returns: result of call. call(Callable<V> `Callable` to call. c) Immediately call a `Callable` with this context as the `current` context.
pack-priv static Context.CancellableContext	cancellableAncestor(Context parent) Returns `parent` if it is a `CancellableContext`, otherwise returns the parent's `cancellableAncestor`.
public Throwable	cancellationCause() If a context `isCancelled()` then return the cause of the cancellation or `null` if context was cancelled without a cause.
pack-priv static <T> T	checkNotNull(T reference, Object errorMessage)
public static Context	current() Return the context associated with the current scope, will never return `null`.
public static Executor	currentContextExecutor(final Executor e) Create an executor that propagates the `current` context when `Executor#execute` is called as the `current` context of the `Runnable` scheduled.
public void	detach(Context toAttach) Reverse an `attach()`, restoring the previous context and exiting the current scope.
public Executor	fixedContextExecutor(final Executor e) Wrap an `Executor` so that it always executes with this context as the `current` context.
public Context	fork() Create a new context which propagates the values of this context but does not cascade its cancellation.
public Deadline	Returns: A `io.grpc.Deadline` or `null` if no deadline is set. getDeadline() A context may have an associated `Deadline` at which it will be automatically cancelled.
public boolean	isCancelled() Is this context cancelled.
pack-priv boolean	isCurrent()
public static <T> Context.Key<T>	key(String a name intended for debugging purposes and does not impact behavior. Multiple different keys may have the same debugString. The value should be not null. debugString) Create a `Key` with the given debug name.
public static <T> Context.Key<T>	keyWithDefault(String a name intended for debugging purposes and does not impact behavior. Multiple different keys may have the same debugString. The value should be not null. debugString, T defaultValue) Create a `Key` with the given debug name and default value.
pack-priv int	listenerCount()
public void	removeListener(Context.CancellationListener cancellationListener) Remove a `CancellationListener`.
public void	run(Runnable `Runnable` to run. r) Immediately run a `Runnable` with this context as the `current` context.
pack-priv static Context.Storage	storage()
private static void	validateGeneration(int generation) If the ancestry chain length is unreasonably long, then print an error to the log and record the stack trace.
public Context.CancellableContext	withCancellation() Create a new context which is independently cancellable and also cascades cancellation from its parent.
public Context.CancellableContext	withDeadline(Deadline newDeadline, ScheduledExecutorService scheduler) Create a new context which will cancel itself at the given `Deadline`.
public Context.CancellableContext	withDeadlineAfter(long duration, TimeUnit unit, ScheduledExecutorService scheduler) Create a new context which will cancel itself after the given `duration` from now.
public <V> Context	withValue(Context.Key<V> k1, V v1) Create a new context with the given key value set.
public <V1, V2> Context	withValues(Context.Key<V1> k1, V1 v1, Context.Key<V2> k2, V2 v2) Create a new context with the given key value set.
public <V1, V2, V3> Context	withValues(Context.Key<V1> k1, V1 v1, Context.Key<V2> k2, V2 v2, Context.Key<V3> k3, V3 v3) Create a new context with the given key value set.
public <V1, V2, V3, V4> Context	withValues(Context.Key<V1> k1, V1 v1, Context.Key<V2> k2, V2 v2, Context.Key<V3> k3, V3 v3, Context.Key<V4> k4, V4 v4) Create a new context with the given key value set.
public Runnable	wrap(final Runnable r) Wrap a `Runnable` so that it executes with this context as the `current` context.
public <C> Callable<C>	wrap(final Callable<C> c) Wrap a `Callable` so that it executes with this context as the `current` context.

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

public Class Context

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary