From 44f3d1eeef7abca3e8c0d53a304c0db3b29ded1c Mon Sep 17 00:00:00 2001
From: Eric Anderson <ejona@google.com>
Date: Mon, 9 Aug 2021 16:06:44 -0700
Subject: [PATCH] api: Document that NameResolvers shouldn't block

Fixes #8190
---
 api/src/main/java/io/grpc/NameResolver.java | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/api/src/main/java/io/grpc/NameResolver.java b/api/src/main/java/io/grpc/NameResolver.java
index cd3a137dfca..f4c05aa6a64 100644
--- 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
  */