Document hand-off to execution thread (including ScheduledFuture impact)

Closes gh-32589

Author: jhoeller

Diff for: spring-context/src/main/java/org/springframework/scheduling/TaskScheduler.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -68,7 +68,7 @@ default Clock getClock() {
 	 * @param trigger an implementation of the {@link Trigger} interface,
 	 * e.g. a {@link org.springframework.scheduling.support.CronTrigger} object
 	 * wrapping a cron expression
-	 * @return a {@link ScheduledFuture} representing pending completion of the task,
+	 * @return a {@link ScheduledFuture} representing pending execution of the task,
 	 * or {@code null} if the given Trigger object never fires (i.e. returns
 	 * {@code null} from {@link Trigger#nextExecution})
 	 * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
@@ -85,7 +85,7 @@ default Clock getClock() {
 	 * @param task the Runnable to execute whenever the trigger fires
 	 * @param startTime the desired execution time for the task
 	 * (if this is in the past, the task will be executed immediately, i.e. as soon as possible)
-	 * @return a {@link ScheduledFuture} representing pending completion of the task
+	 * @return a {@link ScheduledFuture} representing pending execution of the task
 	 * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
 	 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
 	 * @since 5.0
@@ -99,7 +99,7 @@ default Clock getClock() {
 	 * @param task the Runnable to execute whenever the trigger fires
 	 * @param startTime the desired execution time for the task
 	 * (if this is in the past, the task will be executed immediately, i.e. as soon as possible)
-	 * @return a {@link ScheduledFuture} representing pending completion of the task
+	 * @return a {@link ScheduledFuture} representing pending execution of the task
 	 * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
 	 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
 	 * @deprecated as of 6.0, in favor of {@link #schedule(Runnable, Instant)}
@@ -118,7 +118,7 @@ default ScheduledFuture<?> schedule(Runnable task, Date startTime) {
 	 * @param startTime the desired first execution time for the task
 	 * (if this is in the past, the task will be executed immediately, i.e. as soon as possible)
 	 * @param period the interval between successive executions of the task
-	 * @return a {@link ScheduledFuture} representing pending completion of the task
+	 * @return a {@link ScheduledFuture} representing pending execution of the task
 	 * @throws org.springframework.core.task.TaskRejectedException if  the given task was not accepted
 	 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
 	 * @since 5.0
@@ -134,7 +134,7 @@ default ScheduledFuture<?> schedule(Runnable task, Date startTime) {
 	 * @param startTime the desired first execution time for the task
 	 * (if this is in the past, the task will be executed immediately, i.e. as soon as possible)
 	 * @param period the interval between successive executions of the task (in milliseconds)
-	 * @return a {@link ScheduledFuture} representing pending completion of the task
+	 * @return a {@link ScheduledFuture} representing pending execution of the task
 	 * @throws org.springframework.core.task.TaskRejectedException if  the given task was not accepted
 	 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
 	 * @deprecated as of 6.0, in favor of {@link #scheduleAtFixedRate(Runnable, Instant, Duration)}
@@ -151,7 +151,7 @@ default ScheduledFuture<?> scheduleAtFixedRate(Runnable task, Date startTime, lo
 	 * {@link ScheduledFuture} gets cancelled.
 	 * @param task the Runnable to execute whenever the trigger fires
 	 * @param period the interval between successive executions of the task
-	 * @return a {@link ScheduledFuture} representing pending completion of the task
+	 * @return a {@link ScheduledFuture} representing pending execution of the task
 	 * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
 	 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
 	 * @since 5.0
@@ -165,7 +165,7 @@ default ScheduledFuture<?> scheduleAtFixedRate(Runnable task, Date startTime, lo
 	 * {@link ScheduledFuture} gets cancelled.
 	 * @param task the Runnable to execute whenever the trigger fires
 	 * @param period the interval between successive executions of the task (in milliseconds)
-	 * @return a {@link ScheduledFuture} representing pending completion of the task
+	 * @return a {@link ScheduledFuture} representing pending execution of the task
 	 * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
 	 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
 	 * @deprecated as of 6.0, in favor of {@link #scheduleAtFixedRate(Runnable, Duration)}
@@ -185,7 +185,7 @@ default ScheduledFuture<?> scheduleAtFixedRate(Runnable task, long period) {
 	 * @param startTime the desired first execution time for the task
 	 * (if this is in the past, the task will be executed immediately, i.e. as soon as possible)
 	 * @param delay the delay between the completion of one execution and the start of the next
-	 * @return a {@link ScheduledFuture} representing pending completion of the task
+	 * @return a {@link ScheduledFuture} representing pending execution of the task
 	 * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
 	 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
 	 * @since 5.0
@@ -203,7 +203,7 @@ default ScheduledFuture<?> scheduleAtFixedRate(Runnable task, long period) {
 	 * (if this is in the past, the task will be executed immediately, i.e. as soon as possible)
 	 * @param delay the delay between the completion of one execution and the start of the next
 	 * (in milliseconds)
-	 * @return a {@link ScheduledFuture} representing pending completion of the task
+	 * @return a {@link ScheduledFuture} representing pending execution of the task
 	 * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
 	 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
 	 * @deprecated as of 6.0, in favor of {@link #scheduleWithFixedDelay(Runnable, Instant, Duration)}
@@ -220,7 +220,7 @@ default ScheduledFuture<?> scheduleWithFixedDelay(Runnable task, Date startTime,
 	 * {@link ScheduledFuture} gets cancelled.
 	 * @param task the Runnable to execute whenever the trigger fires
 	 * @param delay the delay between the completion of one execution and the start of the next
-	 * @return a {@link ScheduledFuture} representing pending completion of the task
+	 * @return a {@link ScheduledFuture} representing pending execution of the task
 	 * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
 	 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
 	 * @since 5.0
@@ -235,7 +235,7 @@ default ScheduledFuture<?> scheduleWithFixedDelay(Runnable task, Date startTime,
 	 * @param task the Runnable to execute whenever the trigger fires
 	 * @param delay the delay between the completion of one execution and the start of the next
 	 * (in milliseconds)
-	 * @return a {@link ScheduledFuture} representing pending completion of the task
+	 * @return a {@link ScheduledFuture} representing pending execution of the task
 	 * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
 	 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
 	 * @deprecated as of 6.0, in favor of {@link #scheduleWithFixedDelay(Runnable, Duration)}

Diff for: spring-context/src/main/java/org/springframework/scheduling/concurrent/SimpleAsyncTaskScheduler.java

@@ -74,6 +74,12 @@
  * which tend to have specific constraints for the scheduler thread pool,
  * requiring a separate thread pool for general executor purposes in practice.
  *
+ * <p><b>NOTE: This scheduler variant does not track the actual completion of tasks
+ * but rather just the hand-off to an execution thread.</b> As a consequence,
+ * a {@link ScheduledFuture} handle (e.g. from {@link #schedule(Runnable, Instant)})
+ * represents that hand-off rather than the actual completion of the provided task
+ * (or series of repeated tasks).
+ *
  * <p>As an alternative to the built-in thread-per-task capability, this scheduler
  * can also be configured with a separate target executor for scheduled task
  * execution through {@link #setTargetTaskExecutor}: e.g. pointing to a shared

Diff for: spring-context/src/main/java/org/springframework/scheduling/concurrent/ThreadPoolTaskScheduler.java

@@ -48,7 +48,14 @@
 /**
  * A standard implementation of Spring's {@link TaskScheduler} interface, wrapping
  * a native {@link java.util.concurrent.ScheduledThreadPoolExecutor} and providing
- * all applicable configuration options for it.
+ * all applicable configuration options for it. The default number of scheduler
+ * threads is 1; a higher number can be configured through {@link #setPoolSize}.
+ *
+ * <p>This is Spring's traditional scheduler variant, staying as close as possible to
+ * {@link java.util.concurrent.ScheduledExecutorService} semantics. Task execution happens
+ * on the scheduler thread(s) rather than on separate execution threads. As a consequence,
+ * a {@link ScheduledFuture} handle (e.g. from {@link #schedule(Runnable, Instant)})
+ * represents the actual completion of the provided task (or series of repeated tasks).
  *
  * @author Juergen Hoeller
  * @author Mark Fisher
@@ -59,6 +66,8 @@
  * @see #setExecuteExistingDelayedTasksAfterShutdownPolicy
  * @see #setThreadFactory
  * @see #setErrorHandler
+ * @see ThreadPoolTaskExecutor
+ * @see SimpleAsyncTaskScheduler
  */
 @SuppressWarnings({"serial", "deprecation"})
 public class ThreadPoolTaskScheduler extends ExecutorConfigurationSupport