From ae292ba05fc045bc21895dd7a0194b7ec54b50da Mon Sep 17 00:00:00 2001
From: Dean Wette <wetted@objectcomputing.com>
Date: Fri, 29 Apr 2022 04:50:21 -0500
Subject: [PATCH] doc: @Blocking (#7228)

---
 .../threadPools/atBlocking.adoc               | 21 +++++++++++++++++++
 src/main/docs/guide/toc.yml                   |  1 +
 2 files changed, 22 insertions(+)
 create mode 100644 src/main/docs/guide/httpServer/serverConfiguration/threadPools/atBlocking.adoc

diff --git a/src/main/docs/guide/httpServer/serverConfiguration/threadPools/atBlocking.adoc b/src/main/docs/guide/httpServer/serverConfiguration/threadPools/atBlocking.adoc
new file mode 100644
index 00000000000..902ede50829
--- /dev/null
+++ b/src/main/docs/guide/httpServer/serverConfiguration/threadPools/atBlocking.adoc
@@ -0,0 +1,21 @@
+You can use the ann:core.annotation.Blocking[] annotation to mark methods as blocking.
+
+If you set `micronaut.server.thread-selection` to `AUTO`, The Micronaut Framework offloads the execution of methods annotated with `@Blocking` to the IO thread pool (See: api:io.micronaut.scheduling.TaskExecutors[]).
+
+NOTE: `@Blocking` only works if you are using `AUTO` thread selection. Micronaut Framework defaults to `MANUAL` thread selection since Micronaut 2.0. We recommend the usage of ann:scheduling.annotation.ExecuteOn[] annotation to execute the blocking operations on a different thread pool. `@ExecutesOn` works for both `MANUAL` and `AUTO` thread selection.
+
+There are some places where the Micronaut framework uses ann:core.annotation.Blocking[] internally:
+
+|===
+|Blocking Type|Description
+
+|link:{micronautapi}http/client/BlockingHttpClient.html[BlockingHttpClient]
+| Intended for testing, provides blocking versions for a subset of api:http.client.HttpClient[] operations.
+|link:{micronautapi}core/io/IOUtils.html[IOUtils]
+| Reads the contents of a `BufferedReader` in a blocking manner, and returns that as a `String`.
+|link:{micronautapi}context/env/BootstrapPropertySourceLocator.html[BootstrapPropertySourceLocator]
+| Resolves either remote or local api:context.env.PropertySource[] instances for the current `Environment`.
+
+|===
+
+TIP: https://micronaut-projects.github.io/micronaut-data/latest/guide/[Micronaut Data] also utilizes `@Blocking` internally for some transaction operations, CRUD interceptors, and repositories.
diff --git a/src/main/docs/guide/toc.yml b/src/main/docs/guide/toc.yml
index d8a367e2d4a..182b71536df 100644
--- a/src/main/docs/guide/toc.yml
+++ b/src/main/docs/guide/toc.yml
@@ -121,6 +121,7 @@ httpServer:
     threadPools:
       title: Configuring Server Thread Pools
       blockingOperations: Blocking Operations
+      atBlocking: '@Blocking'
     nettyPipeline: Configuring the Netty Pipeline
     cors: Configuring CORS
     https: Securing the Server with HTTPS