Document @Blocking

src/main/docs/guide/httpServer/serverConfiguration/threadPools.adoc

@@ -45,20 +45,3 @@ micronaut:
 ----
 
 The above configuration creates a fixed thread pool with 75 threads.
-
-In Micronaut methods are executed asynchronously by default. For example, methods that return reactive results execute asynchronously in Netty. Others execute in a dedicated I/O thread pool. Sometimes methods that are asynchronous need to execute in a blocking manner. The ann:core.annotation.Blocking[] facilitates this and is used to override default asynchronous execution, by routing calls to the IO executor. Examples might include subscribing to returned reactive types in a blocking manner, or for testing.  ann:core.annotation.Blocking[] is inherited so it can be used as a meta-annotation.
-
-There are some places where the Micronaut framework uses ann:core.annotation.Blocking[] already.
-|===
-|Blocking Type|Description
-
-|link:{micronautapi}http/client/BlockingHttpClient.html[BlockingHttpClient]
-| Intended for testing, and 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` for some transaction operations, CRUD interceptors, and repositories.

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. `@ExecutesOn` works for both `MANUAL` or `AUTO` thread selection.
+
+There are some places where the Micronaut framework uses ann:core.annotation.Blocking[] already.
+
+|===
+|Blocking Type|Description
+
+|link:{micronautapi}http/client/BlockingHttpClient.html[BlockingHttpClient]
+| Intended for testing, and 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` for some transaction operations, CRUD interceptors, and repositories.

src/main/docs/guide/toc.yml

@@ -118,7 +118,9 @@ httpServer:
   serverEvents: Server Events
   serverConfiguration:
     title: Configuring the HTTP Server
-    threadPools: Configuring Server Thread Pools
+    threadPools:
+      title: Configuring Server Thread Pools
+      atBlocking: '@Blocking'
     nettyPipeline: Configuring the Netty Pipeline
     cors: Configuring CORS
     https: Securing the Server with HTTPS