doc(docs.features.taskExecutionAndScheduling): add notes

Author: alfredo-toledano

spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/features/task-execution-and-scheduling.adoc

@@ -1,59 +1,74 @@
 [[features.task-execution-and-scheduling]]
 = Task Execution and Scheduling
 
-In the absence of an `Executor` bean in the context, Spring Boot auto-configures an `AsyncTaskExecutor`.
-When virtual threads are enabled (using Java 21+ and configprop:spring.threads.virtual.enabled[] set to `true`) this will be a `SimpleAsyncTaskExecutor` that uses virtual threads.
-Otherwise, it will be a `ThreadPoolTaskExecutor` with sensible defaults.
-In either case, the auto-configured executor will be automatically used for:
+* if there is NO `Executor` bean | context -> Spring Boot auto-configures an `AsyncTaskExecutor`
+    ** 👀if virtual threads are enabled -> `AsyncTaskExecutor` -- will be a --  `SimpleAsyncTaskExecutor` / uses virtual threads 👀
+        *** way to enable virtual threads
+            **** use Java v21+ &
+            **** `spring.threads.virtual.enabled=true` .
+    ** 👀by default, `AsyncTaskExecutor` -- will be a -- `ThreadPoolTaskExecutor` / sensible defaults 👀
+        *** by default, thread pool uses 8 core threads
+            **** / -- can, according to the load --
+                ***** grow
+                ***** shrink
+                    ****** == if the demand for threads decreases (== tasks complete) -> the thread pool reclaims idle threads -- after a -- certain period of time (by default, 60s)
+            **** if you want to customize it -> specify `spring.task.execution`
 
-- asynchronous task execution (`@EnableAsync`)
-- Spring for GraphQL's asynchronous handling of `Callable` return values from controller methods
-- Spring MVC's asynchronous request processing
-- Spring WebFlux's blocking execution support
+                [configprops,yaml]
+                ----
+                spring:
+                  task:
+                    execution:
+                      pool:
+                        # if the queue is full (100 tasks) -> thread pool -- increases to -- maximum 16 threads
+                        max-size: 16
+                        queue-capacity: 100
+                        keep-alive: "10s"
+                ----
 
-[TIP]
-====
-If you have defined a custom `Executor` in the context, both regular task execution (that is `@EnableAsync`) and Spring for GraphQL will use it.
-However, the Spring MVC and Spring WebFlux support will only use it if it is an `AsyncTaskExecutor` implementation (named `applicationTaskExecutor`).
-Depending on your target arrangement, you could change your `Executor` into an `AsyncTaskExecutor` or define both an `AsyncTaskExecutor` and an `AsyncConfigurer` wrapping your custom `Executor`.
+    ** `AsyncTaskExecutor` is used for
+        *** asynchronous task execution
+            **** == `@EnableAsync`
+        *** Spring for GraphQL's asynchronous handling of `Callable` return values -- from -- controller methods
+        *** Spring MVC's asynchronous request processing
+        *** Spring WebFlux's blocking execution support
+* if you have defined a custom `Executor` | context -> it will be used by
+    ** regular task execution (== `@EnableAsync`)
+    ** Spring for GraphQL
+    ** if it's an `AsyncTaskExecutor` implementation (named `applicationTaskExecutor`)
+        *** -> ALSO used by
+            **** Spring MVC
+            **** Spring WebFlux
+        *** coexistence of `Executor` & `AsyncTaskExecutor` -- depends on -- your target arrangement
+            **** `Executor` -- can be changed into an -- `AsyncTaskExecutor`
+            **** both an `AsyncTaskExecutor` and an `AsyncConfigurer` / wrap your custom `Executor`
+* auto-configured `ThreadPoolTaskExecutorBuilder`
+    ** allows
+        *** creating instances / reproduce what the auto-configuration does by default
+* if scheduler needs to be associated -- with -- scheduled task execution -> it's auto-configured
+    ** _Example for this association:_ use `@EnableScheduling`
+    ** if virtual threads are enabled -> scheduler -- will be a -- `SimpleAsyncTaskScheduler` /
+        *** uses virtual threads
+        *** ignore any pooling related properties
+    ** by default, scheduler -- will be a -- `ThreadPoolTaskScheduler` / sensible defaults
+        *** 1 thread by default
+        *** if you want to customize it -> specify `spring.task.scheduling`
 
-The auto-configured `ThreadPoolTaskExecutorBuilder` allows you to easily create instances that reproduce what the auto-configuration does by default.
-====
+            [configprops,yaml]
+            ----
+            spring:
+              task:
+                scheduling:
+                  thread-name-prefix: "scheduling-"
+                  pool:
+                    size: 2
+            ----
 
-When a `ThreadPoolTaskExecutor` is auto-configured, the thread pool uses 8 core threads that can grow and shrink according to the load.
-Those default settings can be fine-tuned using the `spring.task.execution` namespace, as shown in the following example:
-
-[configprops,yaml]
-----
-spring:
-  task:
-    execution:
-      pool:
-        max-size: 16
-        queue-capacity: 100
-        keep-alive: "10s"
-----
-
-This changes the thread pool to use a bounded queue so that when the queue is full (100 tasks), the thread pool increases to maximum 16 threads.
-Shrinking of the pool is more aggressive as threads are reclaimed when they are idle for 10 seconds (rather than 60 seconds by default).
-
-A scheduler can also be auto-configured if it needs to be associated with scheduled task execution (using `@EnableScheduling` for instance).
-
-If virtual threads are enabled (using Java 21+ and configprop:spring.threads.virtual.enabled[] set to `true`) this will be a `SimpleAsyncTaskScheduler` that uses virtual threads.
-This `SimpleAsyncTaskScheduler` will ignore any pooling related properties.
-
-If virtual threads are not enabled, it will be a `ThreadPoolTaskScheduler` with sensible defaults.
-The `ThreadPoolTaskScheduler` uses one thread by default and its settings can be fine-tuned using the `spring.task.scheduling` namespace, as shown in the following example:
-
-[configprops,yaml]
-----
-spring:
-  task:
-    scheduling:
-      thread-name-prefix: "scheduling-"
-      pool:
-        size: 2
-----
-
-A `ThreadPoolTaskExecutorBuilder` bean, a `SimpleAsyncTaskExecutorBuilder` bean, a `ThreadPoolTaskSchedulerBuilder` bean and a `SimpleAsyncTaskSchedulerBuilder` are made available in the context if a custom executor or scheduler needs to be created.
-The `SimpleAsyncTaskExecutorBuilder` and `SimpleAsyncTaskSchedulerBuilder` beans are auto-configured to use virtual threads if they are enabled (using Java 21+ and configprop:spring.threads.virtual.enabled[] set to `true`).
+* if a custom executor OR scheduler needs to be created -> available | context
+    ** `ThreadPoolTaskExecutorBuilder` bean
+    ** `SimpleAsyncTaskExecutorBuilder` bean
+    ** `ThreadPoolTaskSchedulerBuilder` bean
+    ** `SimpleAsyncTaskSchedulerBuilder` bean
+* if virtual threads are enabled -> beans / auto-configured -- to use -- them
+    ** `SimpleAsyncTaskExecutorBuilder`
+    ** `SimpleAsyncTaskSchedulerBuilder`