io.grpc

Class Context

java.lang.Object

io.grpc.Context

Direct Known Subclasses:

Context.CancellableContext

@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/262")
public class Context
extends Object

A context propagation mechanism which carries deadlines, cancellation signals, and other scoped values across API boundaries and between threads. Examples of functionality propagated via context include:

• Deadlines for a local operation or remote call.
• Security principals and credentials.
• Local and distributed tracing context.

Context objects make their state available by being attached to the executing thread using a ThreadLocal. The context object bound to a thread is considered current(). 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 to the thread replacing the previously bound context. For example:

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

 

Context objects will cascade cancellation from their parent and propagate it to their children. You can add a Context.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 a thread to make it current. To cancel a context (and its descendants) you first create a Context.CancellableContext and when you need to signal cancellation call Context.CancellableContext.cancel(java.lang.Throwable) or Context.CancellableContext.detachAndCancel(io.grpc.Context, java.lang.Throwable). For example:

   CancellableContext withCancellation = Context.current().withCancellation();
   try {
     executorService.execute(withCancellation.wrap(new Runnable() {
       public void run() {
         while (waitingForData() && !Context.current().isCancelled()) {}
       }
     });
     doSomeWork();
   } catch (Throwable t) {
      withCancellation.cancel(t);
   }
 

Notes and cautions on use:

• 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.
• If Context is being used in an environment that needs to support class unloading it is the responsibility of the application to ensure that all contexts are properly cancelled.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
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.
static interface	Context.CancellationListener A listener notified on context cancellation.
static class	Context.Key<T> Key for indexing values stored in a context.

Field Summary

Fields

Modifier and Type	Field and Description
static Context	ROOT The logical root context which is current() if no other context is bound.

Method Summary

Modifier and Type	Method and Description
void	addListener(Context.CancellationListener cancellationListener, Executor executor) Add a listener that will be notified when the context becomes cancelled.
Context	attach() Attach this context to the thread and make it current(), the previously current context is returned.
Throwable	cause() If a context isCancelled() then return the cause of the cancellation or null if context was cancelled without a cause.
static Context	current() Return the context associated with the current thread, will never return null as the ROOT context is implicitly associated with all threads.
void	detach(Context toAttach) Detach the current context from the thread and attach the provided replacement.
Context.CancellableContext	fork() Create a new context which copies the values of this context but does not propagate its cancellation and is its own independent root for cancellation.
boolean	isCancelled() Is this context cancelled.
static <T> Context.Key<T>	key(String name) Create a Context.Key with the given name.
static <T> Context.Key<T>	keyWithDefault(String name, T defaultValue) Create a Context.Key with the given name and default value.
static Executor	propagate(Executor e) Create an executor that propagates the current() context when Executor.execute(java.lang.Runnable) is called to the current() context of the Runnable scheduled.
void	removeListener(Context.CancellationListener cancellationListener) Remove a Context.CancellationListener.
Context.CancellableContext	withCancellation() Create a new context which is independently cancellable and also cascades cancellation from its parent.
Context.CancellableContext	withDeadlineAfter(long duration, TimeUnit unit) Create a new context which will cancel itself after the given duration from now.
Context.CancellableContext	withDeadlineNanoTime(long deadlineNanoTime) Create a new context which will cancel itself after an absolute deadline expressed as nanoseconds in the System.nanoTime() clock.
<V> Context	withValue(Context.Key<V> k1, V v1) Create a new context with the given key value set.
<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.
<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.
<C> Callable<C>	wrap(Callable<C> c) Wrap a Callable so that it executes with this context as the current() context.
Executor	wrap(Executor e) Wrap an Executor so that it executes with this context as the current() context.
Runnable	wrap(Runnable r) Wrap a Runnable so that it executes with this context as the current() context.

Methods inherited from class java.lang.Object

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

Field Detail

ROOT

public static final Context ROOT

The logical root context which is current() if no other context is bound. This context is not cancellable and so will not cascade cancellation or retain listeners.

Method Detail

key

public static <T> Context.Key<T> key(String name)

Create a Context.Key with the given name.

keyWithDefault

public static <T> Context.Key<T> keyWithDefault(String name,
                                                T defaultValue)

Create a Context.Key with the given name and default value.

current

public static Context current()

Return the context associated with the current thread, will never return null as the ROOT context is implicitly associated with all threads.

Will never return Context.CancellableContext even if one is attached, instead a Context is returned with the same properties and lifetime. This is to avoid code stealing the ability to cancel arbitrarily.

withCancellation

public Context.CancellableContext withCancellation()

Create a new context which is independently cancellable and also cascades cancellation from its parent. Callers should ensure that either Context.CancellableContext.cancel(Throwable) or Context.CancellableContext.detachAndCancel(Context, Throwable) are called to notify listeners and release the resources associated with them.

Sample usage:

   Context.CancellableContext withCancellation = Context.current().withCancellation();
   try {
     executorService.execute(withCancellation.wrap(new Runnable() {
       public void run() {
         Context current = Context.current();
         while (!current.isCancelled()) {
           keepWorking();
         }
       }
     });
     doSomethingRelatedWork();
   } catch (Throwable t) {
     withCancellation.cancel(t);
   }
 

withDeadlineNanoTime

public Context.CancellableContext withDeadlineNanoTime(long deadlineNanoTime)

Create a new context which will cancel itself after an absolute deadline expressed as nanoseconds in the System.nanoTime() clock. The returned context will cascade cancellation of its parent. Callers may explicitly cancel the returned context prior to the deadline just as for withCancellation(),

It is recommended that callers only use this method when propagating a derivative of a received existing deadline. When establishing a new deadline, withDeadlineAfter(long, java.util.concurrent.TimeUnit) is the better mechanism.

withDeadlineAfter

public Context.CancellableContext withDeadlineAfter(long duration,
                                                    TimeUnit unit)

Create a new context which will cancel itself after the given duration from now. The returned context will cascade cancellation of its parent. Callers may explicitly cancel the returned context prior to the deadline just as for withCancellation(),

Sample usage:

   Context.CancellableContext withDeadline = Context.current().withDeadlineAfter(5,
       TimeUnit.SECONDS);
   executorService.execute(withDeadline.wrap(new Runnable() {
     public void run() {
       Context current = Context.current();
       while (!current.isCancelled()) {
         keepWorking();
       }
     }
   });
 

withValue

public <V> Context withValue(Context.Key<V> k1,
                             V v1)

Create a new context with the given key value set. The new context will cascade cancellation from its parent.

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

withValues

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. The new context will cascade cancellation from its parent.

withValues

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. The new context will cascade cancellation from its parent.

fork

public Context.CancellableContext fork()

Create a new context which copies the values of this context but does not propagate its cancellation and is its own independent root for cancellation.

attach

public Context attach()

Attach this context to the thread and make it current(), the previously current context is returned. It is allowed to attach contexts where isCancelled() is true.

detach

public void detach(Context toAttach)

Detach the current context from the thread and attach the provided replacement. If this context is not current() a SEVERE message will be logged but the context to attach will still be bound.

isCancelled

public boolean isCancelled()

Is this context cancelled.

cause

@Nullable
public Throwable cause()

If a context isCancelled() then return the cause of the cancellation or null if context was cancelled without a cause. If the context is not yet cancelled will always return null.

The cause is provided for informational purposes only and implementations should generally assume that it has already been handled and logged properly.

addListener

public void addListener(Context.CancellationListener cancellationListener,
                        Executor executor)

Add a listener that will be notified when the context becomes cancelled.

removeListener

public void removeListener(Context.CancellationListener cancellationListener)

Remove a Context.CancellationListener.

wrap

public Runnable wrap(Runnable r)

Wrap a Runnable so that it executes with this context as the current() context.

wrap

public <C> Callable<C> wrap(Callable<C> c)

Wrap a Callable so that it executes with this context as the current() context.

wrap

public Executor wrap(Executor e)

Wrap an Executor so that it executes with this context as the current() context. It is generally expected that propagate(Executor) would be used more commonly than this method.

See Also:

propagate(Executor)

propagate

public static Executor propagate(Executor e)

Create an executor that propagates the current() context when Executor.execute(java.lang.Runnable) is called to the current() context of the Runnable scheduled. Note that this is a static method.

See Also:

wrap(Executor)