Class Context.CancellableContext
- All Implemented Interfaces:
Closeable
,AutoCloseable
- Enclosing class:
Context
This class must be cancelled by either calling close()
or cancel(java.lang.Throwable)
.
close()
is equivalent to calling 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 close()
at the end of
the operation, and disregard whether cancel(java.lang.Throwable)
was already called somewhere else.
Blocking code can use the try-with-resources idiom:
try (CancellableContext c = Context.current() .withDeadlineAfter(100, TimeUnit.MILLISECONDS, executor)) { Context toRestore = c.attach(); try { // do some blocking work } finally { c.detach(toRestore); } }
Asynchronous code will have to manually track the end of the CancellableContext's lifetime, and cancel the context at the appropriate time.
-
Nested Class Summary
Nested classes/interfaces inherited from class io.grpc.Context
Context.CancellableContext, Context.CancellationListener, Context.CanIgnoreReturnValue, Context.CheckReturnValue, Context.Key<T>, Context.Storage
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate Throwable
private boolean
private final Deadline
private ArrayList
<Context.ExecutableListener> private Context.CancellationListener
private ScheduledFuture
<?> private final Context
Fields inherited from class io.grpc.Context
cancellableAncestor, CONTEXT_DEPTH_WARN_THRESH, generation, keyValueEntries, log, ROOT
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
CancellableContext
(Context parent) Create a cancellable context that does not have a deadline.private
CancellableContext
(Context parent, Deadline deadline) Create a cancellable context that has a deadline. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addListener
(Context.CancellationListener cancellationListener, Executor executor) Add a listener that will be notified when the context becomes cancelled.private void
addListenerInternal
(Context.ExecutableListener executableListener) attach()
Attach this context, thus enter a new scope within which this context isContext.current()
.boolean
Cancel this context and optionally provide a cause (can benull
) for the cancellation.If a contextContext.isCancelled()
then return the cause of the cancellation ornull
if context was cancelled without a cause.void
close()
Cleans up this object by callingcancel(null)
.void
Reverse anattach()
, restoring the previous context and exiting the current scope.void
detachAndCancel
(Context toAttach, Throwable cause) Cancel this context and detach it as the current context.A context may have an associatedDeadline
at which it will be automatically cancelled.boolean
Is this context cancelled.boolean
Deprecated.This method violates some GRPC class encapsulation and should not be used.(package private) int
private void
Notify all listeners that this context has been cancelled and immediately release any reference to them so that they may be garbage collected.void
removeListener
(Context.CancellationListener cancellationListener) Remove aContext.CancellationListener
.private void
removeListenerInternal
(Context.CancellationListener cancellationListener, Context context) private void
setUpDeadlineCancellation
(Deadline deadline, ScheduledExecutorService scheduler) Methods inherited from class io.grpc.Context
call, cancellableAncestor, checkNotNull, current, currentContextExecutor, fixedContextExecutor, fork, key, keyWithDefault, run, storage, withCancellation, withDeadline, withDeadlineAfter, withValue, withValues, withValues, withValues, wrap, wrap
-
Field Details
-
deadline
-
uncancellableSurrogate
-
listeners
-
parentListener
-
cancellationCause
-
pendingDeadline
-
cancelled
private boolean cancelled
-
-
Constructor Details
-
CancellableContext
Create a cancellable context that does not have a deadline. -
CancellableContext
Create a cancellable context that has a deadline.
-
-
Method Details
-
setUpDeadlineCancellation
-
attach
Description copied from class:Context
Attach this context, thus enter a new scope within which this context isContext.current()
. The previously current context is returned. It is allowed to attach contexts whereContext.isCancelled()
istrue
.Instead of using
attach()
andContext.detach(Context)
most use-cases are better served by using theContext.run(Runnable)
orContext.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
attach()
should have a correspondingContext.detach(Context)
within the same method:Context previous = someContext.attach(); try { // Do work } finally { someContext.detach(previous); }
-
detach
Description copied from class:Context
Reverse anattach()
, restoring the previous context and exiting the current scope.This context should be the same context that was previously
attached
. The provided replacement should be what was returned by the sameattach()
call. If anattach()
and adetach()
meet above requirements, they match.It is expected that between any pair of matching
attach()
anddetach()
, allattach()
es anddetach()
es are called in matching pairs. If this method finds that this context is notcurrent
, 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 useContext.current().detach()
, as this will compromise this error-detecting mechanism. -
addListener
Description copied from class:Context
Add a listener that will be notified when the context becomes cancelled.- Overrides:
addListener
in classContext
-
addListenerInternal
-
removeListener
Description copied from class:Context
Remove aContext.CancellationListener
.- Overrides:
removeListener
in classContext
-
removeListenerInternal
private void removeListenerInternal(Context.CancellationListener cancellationListener, Context context) -
isCurrent
Deprecated.This method violates some GRPC class encapsulation and should not be used. If you must know whether a Context is the current context, check whether it is the same object returned byContext.current()
.Returns true if the Context is the current context. -
cancel
Cancel this context and optionally provide a cause (can benull
) for the cancellation. This will trigger notification of listeners. It is safe to call this method multiple times. Only the first call will have any effect.Calling
cancel(null)
is the same as callingclose()
.- Returns:
true
if this context cancelled the context and notified listeners,false
if the context was already cancelled.
-
notifyAndClearListeners
private void notifyAndClearListeners()Notify all listeners that this context has been cancelled and immediately release any reference to them so that they may be garbage collected. -
listenerCount
int listenerCount()- Overrides:
listenerCount
in classContext
-
detachAndCancel
Cancel this context and detach it as the current context.- Parameters:
toAttach
- context to make current.cause
- of cancellation, can benull
.
-
isCancelled
public boolean isCancelled()Description copied from class:Context
Is this context cancelled.- Overrides:
isCancelled
in classContext
-
cancellationCause
Description copied from class:Context
If a contextContext.isCancelled()
then return the cause of the cancellation ornull
if context was cancelled without a cause. If the context is not yet cancelled will always returnnull
.The cancellation cause is provided for informational purposes only and implementations should generally assume that it has already been handled and logged properly.
- Overrides:
cancellationCause
in classContext
-
getDeadline
Description copied from class:Context
A context may have an associatedDeadline
at which it will be automatically cancelled.- Overrides:
getDeadline
in classContext
- Returns:
- A
Deadline
ornull
if no deadline is set.
-
close
public void close()Cleans up this object by callingcancel(null)
.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
-