From 3c931b40b0b95e2e4b167f68c07ffa615c76ba9f Mon Sep 17 00:00:00 2001 From: Eric Anderson Date: Thu, 30 May 2019 10:12:33 -0700 Subject: [PATCH] api: Mention similarity of synccontext to a dedicated thread This is the conceptual model we use. Document it to help aid others' understanding and make it easier to understand when it is appropriate to use. --- api/src/main/java/io/grpc/SynchronizationContext.java | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/api/src/main/java/io/grpc/SynchronizationContext.java b/api/src/main/java/io/grpc/SynchronizationContext.java index b577d18e6a..03d26b55f0 100644 --- a/api/src/main/java/io/grpc/SynchronizationContext.java +++ b/api/src/main/java/io/grpc/SynchronizationContext.java @@ -45,6 +45,13 @@ import javax.annotation.concurrent.ThreadSafe; * *

It doesn't own any thread. Tasks are run from caller's or caller-provided threads. * + *

Conceptually, it is fairly accurate to think of {@code SynchronizationContext} like a cheaper + * {@code Executors.newSingleThreadExecutor()} when used for synchronization (not long-running + * tasks). Both use a queue for tasks that are run in order and neither guarantee that tasks have + * completed before returning from {@code execute()}. However, the behavior does diverge if locks + * are held when calling the context. So it is encouraged to avoid mixing locks and synchronization + * context except via {@link #executeLater}. + * *

This class is thread-safe. * * @since 1.17.0