diff --git a/spring-context/src/main/java/org/springframework/scheduling/TaskScheduler.java b/spring-context/src/main/java/org/springframework/scheduling/TaskScheduler.java index a99d6069201..a9a9d4949a5 100644 --- a/spring-context/src/main/java/org/springframework/scheduling/TaskScheduler.java +++ b/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 @@ public interface TaskScheduler { * @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 @@ public interface TaskScheduler { * @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 @@ public interface TaskScheduler { * @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 @@ public interface TaskScheduler { * @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 @@ public interface TaskScheduler { * @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 @@ public interface TaskScheduler { * {@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 @@ public interface TaskScheduler { * {@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 @@ public interface TaskScheduler { * @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 @@ public interface TaskScheduler { * (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 @@ public interface TaskScheduler { * {@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 @@ public interface TaskScheduler { * @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 --git a/spring-context/src/main/java/org/springframework/scheduling/concurrent/SimpleAsyncTaskScheduler.java b/spring-context/src/main/java/org/springframework/scheduling/concurrent/SimpleAsyncTaskScheduler.java index debb853d3ca..7f341092a16 100644 --- a/spring-context/src/main/java/org/springframework/scheduling/concurrent/SimpleAsyncTaskScheduler.java +++ b/spring-context/src/main/java/org/springframework/scheduling/concurrent/SimpleAsyncTaskScheduler.java @@ -74,6 +74,12 @@ import org.springframework.util.ErrorHandler; * which tend to have specific constraints for the scheduler thread pool, * requiring a separate thread pool for general executor purposes in practice. * + *

NOTE: This scheduler variant does not track the actual completion of tasks + * but rather just the hand-off to an execution thread. 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). + * *

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 --git a/spring-context/src/main/java/org/springframework/scheduling/concurrent/ThreadPoolTaskScheduler.java b/spring-context/src/main/java/org/springframework/scheduling/concurrent/ThreadPoolTaskScheduler.java index 65b2e948728..1783220223d 100644 --- a/spring-context/src/main/java/org/springframework/scheduling/concurrent/ThreadPoolTaskScheduler.java +++ b/spring-context/src/main/java/org/springframework/scheduling/concurrent/ThreadPoolTaskScheduler.java @@ -48,7 +48,14 @@ import org.springframework.util.concurrent.ListenableFutureTask; /** * 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}. + * + *

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 @@ import org.springframework.util.concurrent.ListenableFutureTask; * @see #setExecuteExistingDelayedTasksAfterShutdownPolicy * @see #setThreadFactory * @see #setErrorHandler + * @see ThreadPoolTaskExecutor + * @see SimpleAsyncTaskScheduler */ @SuppressWarnings({"serial", "deprecation"}) public class ThreadPoolTaskScheduler extends ExecutorConfigurationSupport