api: Document that NameResolvers shouldn't block

Fixes #8190
grpc · Aug 9, 2021 · 51d1484 · 51d1484
1 parent bb06739
commit 51d1484
Showing 1 changed file with 3 additions and 1 deletion.
diff --git a/api/src/main/java/io/grpc/NameResolver.java b/api/src/main/java/io/grpc/NameResolver.java
@@ -50,7 +50,9 @@
  * <p>Implementations <strong>don't need to be thread-safe</strong>.  All methods are guaranteed to
  * be called sequentially.  Additionally, all methods that have side-effects, i.e.,
  * {@link #start(Listener2)}, {@link #shutdown} and {@link #refresh} are called from the same
- * {@link SynchronizationContext} as returned by {@link Args#getSynchronizationContext}.
+ * {@link SynchronizationContext} as returned by {@link Args#getSynchronizationContext}. <strong>Do
+ * not block</strong> within the synchronization context; blocking I/O and time-consuming tasks
+ * should be offloaded to a separate thread, generally {@link Args#getOffloadExecutor}.
  *
  * @since 1.0.0
  */