Package io.grpc

Class Context.CancellableContext

  • All Implemented Interfaces:
    Closeable, AutoCloseable
    Enclosing class:
    Context
    public static final class Context.CancellableContext
extends Context
implements Closeable
    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 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.

    • Method Detail

      • detach

        public void detach​(Context toAttach)
        Description copied from class: Context
        Reverse an attach(), 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 same attach() call. If an attach() and a detach() meet above requirements, they match.

        It is expected that between any pair of matching attach() and detach(), all attach()es and detach()es are called in matching pairs. If this method finds that this context is not 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 Context.current().detach(), as this will compromise this error-detecting mechanism.

        Overrides:
        detach in class Context

      • isCurrent

        @Deprecated
public boolean 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 by Context.current().
        Returns true if the Context is the current context.

      • cancel

        public boolean cancel​(Throwable cause)
        Cancel this context and optionally provide a cause (can be null) 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 calling close().

        Returns:
        true if this context cancelled the context and notified listeners, false if the context was already cancelled.

      • detachAndCancel

        public void detachAndCancel​(Context toAttach,
                            Throwable cause)
        Cancel this context and detach it as the current context.
        Parameters:
        toAttach - context to make current.
        cause - of cancellation, can be null.

      • isCancelled

        public boolean isCancelled()
        Description copied from class: Context
        Is this context cancelled.
        Overrides:
        isCancelled in class Context

      • cancellationCause

        public Throwable cancellationCause()
        Description copied from class: Context
        If a context 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 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 class Context

      • getDeadline

        public Deadline getDeadline()
        Description copied from class: Context
        A context may have an associated Deadline at which it will be automatically cancelled.
        Overrides:
        getDeadline in class Context
        Returns:
        A Deadline or null if no deadline is set.

      • close

        public void close()
        Cleans up this object by calling cancel(null).
        Specified by:
        close in interface AutoCloseable
        Specified by:
        close in interface Closeable