Add Warnings in the async client interface and CrtClient against pass…

…ing Runnable::run (#5016)

* Add Warnings in the async client interface and CrtClient against passing in Runnable::run

* Update warning message

* Updated warning message

* Added paragraph notation

* Add a paragraph notation

codegen/src/main/java/software/amazon/awssdk/codegen/poet/client/AsyncClientInterface.java

@@ -169,7 +169,13 @@ public ClassName className() {
 
     private String getJavadoc() {
         return "Service client for accessing " + model.getMetadata().getDescriptiveServiceName() + " asynchronously. This can be "
-               + "created using the static {@link #builder()} method.\n\n" + model.getMetadata().getDocumentation();
+               + "created using the static {@link #builder()} method."
+               + "The asynchronous client performs non-blocking I/O when configured "
+               + "with any {@link SdkAsyncHttpClient} supported in the SDK. "
+               + "However, full non-blocking is not guaranteed as the async client may perform "
+               + "blocking calls in some cases such as credentials retrieval and "
+               + "endpoint discovery as part of the async API call."
+               + "\n\n" + model.getMetadata().getDocumentation();
     }
 
     private MethodSpec create() {

codegen/src/test/resources/software/amazon/awssdk/codegen/poet/client/test-json-async-client-interface.java

@@ -53,7 +53,9 @@
 
 /**
  * Service client for accessing Json Service asynchronously. This can be created using the static {@link #builder()}
- * method.
+ * method.The asynchronous client performs non-blocking I/O when configured with any {@link SdkAsyncHttpClient}
+ * supported in the SDK. However, full non-blocking is not guaranteed as the async client may perform blocking calls in
+ * some cases such as credentials retrieval and endpoint discovery as part of the async API call.
  *
  * A service that is implemented using the query protocol
  */

services/s3/src/main/java/software/amazon/awssdk/services/s3/S3CrtAsyncClientBuilder.java

@@ -322,10 +322,12 @@ default S3CrtAsyncClientBuilder retryConfiguration(Consumer<S3CrtRetryConfigurat
      *     <li>You want more fine-grained control over the {@link ThreadPoolExecutor} used, such as configuring the pool size
      *     or sharing a single pool between multiple clients.
      *     <li>You want to add instrumentation (i.e., metrics) around how the {@link Executor} is used.
-     *     <li>You know, for certain, that all of your {@link CompletableFuture} usage is strictly non-blocking, and you wish to
-     *     remove the minor overhead incurred by using a separate thread. In this case, you can use
-     *     {@code Runnable::run} to execute the future-completion directly from within the I/O thread.
      * </ol>
+     * <p>
+     * <b>WARNING</b>
+     * We strongly <strong>discourage</strong> using {@code Runnable::run}, which executes the future-completion directly from
+     * within the I/O thread because it may block the I/O thread and cause deadlock, especially if you are sending
+     * another SDK request in the {@link CompletableFuture} chain since the SDK may perform blocking calls in some cases.
      *
      * @param futureCompletionExecutor the executor
      * @return an instance of this builder.