From 979508ea442c9ec7563fea3fc88914c82245cb08 Mon Sep 17 00:00:00 2001 From: Eric Anderson Date: Mon, 4 Oct 2021 12:29:28 -0700 Subject: [PATCH] context: Remove misleading example that leaks CancellableContext The example should unconditionally cancel the context, but fails to. And it is really unclear what situation the example is demonstrating as the Runnable looping on isCancelled() is guaranteed to have returned when the Throwable catch is run. It is non-trivial to fix up this example such that it is concise, useful, and correct as it essentially needs a rewrite. We have other examples demonstrating CancellableContext usage. We can just rely on them instead. --- context/src/main/java/io/grpc/Context.java | 17 ++--------------- 1 file changed, 2 insertions(+), 15 deletions(-) diff --git a/context/src/main/java/io/grpc/Context.java b/context/src/main/java/io/grpc/Context.java index 142cd3cadb..ad47ca9cb4 100644 --- a/context/src/main/java/io/grpc/Context.java +++ b/context/src/main/java/io/grpc/Context.java @@ -57,26 +57,13 @@ import java.util.logging.Logger; * * *

Contexts are also used to represent a scoped unit of work. When the unit of work is done the - * context can be cancelled. This cancellation will also cascade to all descendant contexts. You can + * 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}. For example: - * 

- *   CancellableContext withCancellation = Context.current().withCancellation();
- *   try {
- *     withCancellation.run(new Runnable() {
- *       public void run() {
- *         while (waitingForData() && !Context.current().isCancelled()) {}
- *       }
- *     });
- *     doSomeWork();
- *   } catch (Throwable t) {
- *      withCancellation.cancel(t);
- *   }
- *
+ * 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.