A Context object can be {@link #attach attached} to the {@link 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 {@link #current}. The scope is * later exited by {@link #detach 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 {@link 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 {@link #attach()} an already cancelled context to make it current. To cancel a * context (and its descendants) you first create a {@link CancellableContext} and when you need to * signal cancellation call {@link CancellableContext#cancel} or {@link * 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: *
Never assume this is the default context for new threads, because {@link Storage} may define
* a default context that is different from ROOT.
*/
public static final Context ROOT = new Context();
// Visible For testing
static Storage storage() {
return LazyStorage.storage;
}
// Lazy-loaded storage. Delaying storage initialization until after class initialization makes it
// much easier to avoid circular loading since there can still be references to Context as long as
// they don't depend on storage, like key() and currentContextExecutor(). It also makes it easier
// to handle exceptions.
private static final class LazyStorage {
static final Storage storage;
static {
AtomicReference Will never return {@link CancellableContext} even if one is attached, instead a
* {@link Context} is returned with the same properties and lifetime. This is to avoid
* code stealing the ability to cancel arbitrarily.
*/
public static Context current() {
Context current = storage().current();
if (current == null) {
return ROOT;
}
return current;
}
final CancellableContext cancellableAncestor;
final Node Sample usage:
* Sample usage:
* Sample usage:
* Note that multiple calls to {@link #withValue} can be chained together.
* That is,
*
* Nonetheless, {@link Context} should not be treated like a general purpose
* map with a large number of keys and values — combine multiple related items
* together into a single key instead of separating them. But if the items
* are unrelated, have separate keys for them.
*/
public For more than 4 key-value pairs, note that multiple calls to
* {@link #withValue} can be chained together. That is,
*
* Nonetheless, {@link Context} should not be treated like a general purpose
* map with a large number of keys and values — combine multiple related items
* together into a single key instead of separating them. But if the items
* are unrelated, have separate keys for them.
*/
public Instead of using {@code attach()} and {@link #detach(Context)} most use-cases are better
* served by using the {@link #run(Runnable)} or {@link #call(java.util.concurrent.Callable)} to
* execute work immediately within a context's scope. If work needs to be done in other threads it
* is recommended to use the 'wrap' methods or to use a propagating executor.
*
* All calls to {@code attach()} should have a corresponding {@link #detach(Context)} within
* the same method:
* This context should be the same context that was previously {@link #attach attached}. The
* provided replacement should be what was returned by the same {@link #attach attach()} call. If
* an {@code attach()} and a {@code detach()} meet above requirements, they match.
*
* It is expected that between any pair of matching {@code attach()} and {@code detach()}, all
* {@code attach()}es and {@code detach()}es are called in matching pairs. If this method finds
* that this context is not {@link #current current}, either you or some code in-between are not
* detaching correctly, and a SEVERE message will be logged but the context to attach will still
* be bound. Never use {@code Context.current().detach()}, as this will
* compromise this error-detecting mechanism.
*/
public void detach(Context toAttach) {
checkNotNull(toAttach, "toAttach");
storage().detach(this, toAttach);
}
// Visible for testing
boolean isCurrent() {
return current() == this;
}
/**
* Is this context cancelled.
*/
public boolean isCancelled() {
if (cancellableAncestor == null) {
return false;
} else {
return cancellableAncestor.isCancelled();
}
}
/**
* If a context {@link #isCancelled()} then return the cause of the cancellation or
* {@code null} if context was cancelled without a cause. If the context is not yet cancelled
* will always return {@code null}.
*
* The cancellation cause is provided for informational purposes only and implementations
* should generally assume that it has already been handled and logged properly.
*/
public Throwable cancellationCause() {
if (cancellableAncestor == null) {
return null;
} else {
return cancellableAncestor.cancellationCause();
}
}
/**
* A context may have an associated {@link Deadline} at which it will be automatically cancelled.
* @return A {@link io.grpc.Deadline} or {@code null} if no deadline is set.
*/
public Deadline getDeadline() {
if (cancellableAncestor == null) {
return null;
}
return cancellableAncestor.getDeadline();
}
/**
* Add a listener that will be notified when the context becomes cancelled.
*/
public void addListener(final CancellationListener cancellationListener,
final Executor executor) {
checkNotNull(cancellationListener, "cancellationListener");
checkNotNull(executor, "executor");
if (cancellableAncestor == null) {
return;
}
cancellableAncestor.addListenerInternal(
new ExecutableListener(executor, cancellationListener, this));
}
/**
* Remove a {@link CancellationListener}.
*/
public void removeListener(CancellationListener cancellationListener) {
if (cancellableAncestor == null) {
return;
}
cancellableAncestor.removeListenerInternal(cancellationListener, this);
}
// Used in tests to ensure that listeners are defined and released when cancellation cascades.
// It's very important to ensure that we do not accidentally retain listeners.
int listenerCount() {
if (cancellableAncestor == null) {
return 0;
}
return cancellableAncestor.listenerCount();
}
/**
* Immediately run a {@link Runnable} with this context as the {@link #current} context.
* @param r {@link Runnable} to run.
*/
public void run(Runnable r) {
Context previous = attach();
try {
r.run();
} finally {
detach(previous);
}
}
/**
* Immediately call a {@link Callable} with this context as the {@link #current} context.
* @param c {@link Callable} to call.
* @return result of call.
*/
@CanIgnoreReturnValue
public One scenario in which this executor may be useful is when a single thread is sharding work
* to multiple threads.
*
* @see #currentContextExecutor(Executor)
*/
public Executor fixedContextExecutor(final Executor e) {
final class FixedContextExecutor implements Executor {
@Override
public void execute(Runnable r) {
e.execute(wrap(r));
}
}
return new FixedContextExecutor();
}
/**
* Create an executor that propagates the {@link #current} context when {@link Executor#execute}
* is called as the {@link #current} context of the {@code Runnable} scheduled. Note that this
* is a static method.
*
* @see #fixedContextExecutor(Executor)
*/
public static Executor currentContextExecutor(final Executor e) {
final class CurrentContextExecutor implements Executor {
@Override
public void execute(Runnable r) {
e.execute(Context.current().wrap(r));
}
}
return new CurrentContextExecutor();
}
/**
* A context which inherits cancellation from its parent but which can also be independently
* cancelled and which will propagate cancellation to its descendants. To avoid leaking memory,
* every CancellableContext must have a defined lifetime, after which it is guaranteed to be
* cancelled.
*
* This class must be cancelled by either calling {@link #close} or {@link #cancel}.
* {@link #close} is equivalent to calling {@code cancel(null)}. It is safe to call the methods
* more than once, but only the first call will have any effect. Because it's safe to call the
* methods multiple times, users are encouraged to always call {@link #close} at the end of
* the operation, and disregard whether {@link #cancel} was already called somewhere else.
*
* Blocking code can use the try-with-resources idiom:
* Asynchronous code will have to manually track the end of the CancellableContext's lifetime,
* and cancel the context at the appropriate time.
*/
public static final class CancellableContext extends Context implements Closeable {
private final Deadline deadline;
private final Context uncancellableSurrogate;
private ArrayList Calling {@code cancel(null)} is the same as calling {@link #close}.
*
* @return {@code true} if this context cancelled the context and notified listeners,
* {@code false} if the context was already cancelled.
*/
@CanIgnoreReturnValue
public boolean cancel(Throwable cause) {
boolean triggeredCancel = false;
ScheduledFuture localPendingDeadline = null;
synchronized (this) {
if (!cancelled) {
cancelled = true;
if (pendingDeadline != null) {
// If we have a scheduled cancellation pending attempt to cancel it.
localPendingDeadline = pendingDeadline;
pendingDeadline = null;
}
this.cancellationCause = cause;
triggeredCancel = true;
}
}
if (localPendingDeadline != null) {
localPendingDeadline.cancel(false);
}
if (triggeredCancel) {
notifyAndClearListeners();
}
return triggeredCancel;
}
/**
* Notify all listeners that this context has been cancelled and immediately release
* any reference to them so that they may be garbage collected.
*/
private void notifyAndClearListeners() {
ArrayList The default implementation will put the current context in a {@link ThreadLocal}. If an
* alternative implementation named {@code io.grpc.override.ContextStorageOverride} exists in the
* classpath, it will be used instead of the default implementation.
*
* This API is experimental and
* subject to change.
*/
public abstract static class Storage {
/**
* Unused.
*
* @deprecated This is an old API that is no longer used.
*/
@Deprecated
public void attach(Context toAttach) {
throw new UnsupportedOperationException("Deprecated. Do not call.");
}
/**
* Implements {@link io.grpc.Context#attach}.
*
* Caution: {@link Context#attach()} interprets a return value of {@code null} to mean
* the same thing as {@link Context#ROOT}.
*
* See also: {@link #current()}.
* @param toAttach the context to be attached
* @return A {@link Context} that should be passed back into {@link #detach(Context, Context)}
* as the {@code toRestore} parameter. {@code null} is a valid return value, but see
* caution note.
*/
public Context doAttach(Context toAttach) {
// This is a default implementation to help migrate existing Storage implementations that
// have an attach() method but no doAttach() method.
Context current = current();
attach(toAttach);
return current;
}
/**
* Implements {@link io.grpc.Context#detach}.
*
* @param toDetach the context to be detached. Should be, or be equivalent to, the current
* context of the current scope
* @param toRestore the context to be the current. Should be, or be equivalent to, the context
* of the outer scope
*/
public abstract void detach(Context toDetach, Context toRestore);
/**
* Implements {@link io.grpc.Context#current}.
*
* Caution: {@link Context} interprets a return value of {@code null} to mean the same
* thing as {@link Context#ROOT}.
*
* See also {@link #doAttach(Context)}.
*
* @return The context of the current scope. {@code null} is a valid return value, but see
* caution note.
*/
public abstract Context current();
}
/**
* Stores listener and executor pair.
*/
private static final class ExecutableListener implements Runnable {
private final Executor executor;
final CancellationListener listener;
private final Context context;
ExecutableListener(Executor executor, CancellationListener listener, Context context) {
this.executor = executor;
this.listener = listener;
this.context = context;
}
void deliver() {
try {
executor.execute(this);
} catch (Throwable t) {
log.log(Level.INFO, "Exception notifying context listener", t);
}
}
@Override
public void run() {
listener.cancelled(context);
}
}
@CanIgnoreReturnValue
static
* Context.CancellableContext withCancellation = Context.current().withCancellation();
* try {
* withCancellation.run(new Runnable() {
* public void run() {
* Context current = Context.current();
* while (!current.isCancelled()) {
* keepWorking();
* }
* }
* });
* } finally {
* withCancellation.cancel(null);
* }
*
*/
public CancellableContext withCancellation() {
return new CancellableContext(this);
}
/**
* Create a new context which will cancel itself after the given {@code 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 {@link #withCancellation()}. If the unit
* of work completes before the deadline, the context should be explicitly cancelled to allow
* it to be garbage collected.
*
*
* Context.CancellableContext withDeadline = Context.current()
* .withDeadlineAfter(5, TimeUnit.SECONDS, scheduler);
* try {
* withDeadline.run(new Runnable() {
* public void run() {
* Context current = Context.current();
* while (!current.isCancelled()) {
* keepWorking();
* }
* }
* });
* } finally {
* withDeadline.cancel(null);
* }
*
*/
public CancellableContext withDeadlineAfter(long duration, TimeUnit unit,
ScheduledExecutorService scheduler) {
return withDeadline(Deadline.after(duration, unit), scheduler);
}
/**
* Create a new context which will cancel itself at the given {@link Deadline}.
* The returned context will cascade cancellation of its parent. Callers may explicitly cancel
* the returned context prior to the deadline just as for {@link #withCancellation()}. If the unit
* of work completes before the deadline, the context should be explicitly cancelled to allow
* it to be garbage collected.
*
*
* Context.CancellableContext withDeadline = Context.current()
* .withDeadline(someReceivedDeadline, scheduler);
* try {
* withDeadline.run(new Runnable() {
* public void run() {
* Context current = Context.current();
* while (!current.isCancelled() && moreWorkToDo()) {
* keepWorking();
* }
* }
* });
* } finally {
* withDeadline.cancel(null);
* }
*
*/
public CancellableContext withDeadline(Deadline newDeadline, ScheduledExecutorService scheduler) {
checkNotNull(newDeadline, "deadline");
checkNotNull(scheduler, "scheduler");
Deadline existingDeadline = getDeadline();
boolean scheduleDeadlineCancellation = true;
if (existingDeadline != null && existingDeadline.compareTo(newDeadline) <= 0) {
// The new deadline won't have an effect, so ignore it
newDeadline = existingDeadline;
scheduleDeadlineCancellation = false;
}
CancellableContext newCtx = new CancellableContext(this, newDeadline);
if (scheduleDeadlineCancellation) {
newCtx.setUpDeadlineCancellation(newDeadline, scheduler);
}
return newCtx;
}
/**
* 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);
* withCredential.run(new Runnable() {
* public void run() {
* readUserRecords(userId, CRED_KEY.get());
* }
* });
*
*
*
* context.withValues(K1, V1, K2, V2);
* // is the same as
* context.withValue(K1, V1).withValue(K2, V2);
*
*
*
* context.withValues(K1, V1, K2, V2);
* // is the same as
* context.withValue(K1, V1).withValue(K2, V2);
*
*
* {@code Context previous = someContext.attach();
* try {
* // Do work
* } finally {
* someContext.detach(previous);
* }}
*/
public Context attach() {
Context prev = storage().doAttach(this);
if (prev == null) {
return ROOT;
}
return prev;
}
/**
* Reverse an {@code attach()}, restoring the previous context and exiting the current scope.
*
*
* try (CancellableContext c = Context.current()
* .withDeadlineAfter(100, TimeUnit.MILLISECONDS, executor)) {
* Context toRestore = c.attach();
* try {
* // do some blocking work
* } finally {
* c.detach(toRestore);
* }
* }
*
*