Merge pull request #46100 from manovotn/schedulerLongRunningTasks

Scheduler - document scheduling long running tasks

Author: mkouba

docs/src/main/asciidoc/scheduler-reference.adoc

@@ -442,6 +442,57 @@ class MyService {
 
 NOTE: A CDI event is fired synchronously and asynchronously when the scheduler or a scheduled job is paused/resumed. The payload is `io.quarkus.scheduler.SchedulerPaused`, `io.quarkus.scheduler.SchedulerResumed`, `io.quarkus.scheduler.ScheduledJobPaused` and `io.quarkus.scheduler.ScheduledJobResumed` respectively.
 
+[[scheduling_long_running_tasks]]
+== Scheduling Long-Running Tasks
+
+Executing a long-running task might yield a warning message similar to the following:
+
+[source,java]
+----
+WARN  [io.ver.cor.imp.BlockedThreadChecker] (vertx-blocked-thread-checker) Thread Thread[vert.x-worker-thread-1,5,main] has been blocked for 81879 ms, time limit is 60000 ms: io.vertx.core.VertxException: Thread blocked
+----
+
+This is happening because the default worker thread pool is coming from Vert.x which guards against threads being blocked for far too long.
+
+NOTE: The amount of time for which a Vert.x worker thread can be blocked is also https://quarkus.io/guides/all-config#quarkus-vertx_quarkus-vertx-max-worker-execute-time[configurable].
+
+Therefore, a proper way to execute long tasks is to offload them from the scheduled method to a custom executor service.
+Here's an example of such setup for a long-running task that we do not expect to execute often:
+
+[source,java]
+----
+@ApplicationScoped
+public class LongRunner implements Runnable {
+    
+    private ExecutorService executorService;
+    
+    @PostConstruct
+    void init() {
+        executorService = Executors.newThreadPerTaskExecutor(Executors.defaultThreadFactory()); <1>
+    }
+    
+    @PreDestroy
+    void destroy() {
+        executorService.shutdown(); <2>
+    }
+    
+    
+    @Scheduled(cron = "{my.schedule}")
+    public void update() {
+        executorService.execute(this); <3>
+    }
+    
+    @Override
+    public void run() { <4>
+        // perform the actual task here
+    }
+}
+----
+<1> Create a fitting executor. In this case, a new thread is created per scheduled task and stopped once the task finishes.
+<2> `@PreDestroy` callback is used to shut down the executor service.
+<3> Scheduled method only delegates the job to the custom executor - this prevent Vert.x thread from being blocked.
+<4> The bean implements `Runnable`, a format we can directly pass to the executor service as a parameter.
+
 [[programmatic_scheduling]]
 == Programmatic Scheduling