Merge branch '6.1.x'

spring-aspects/src/main/java/org/springframework/scheduling/aspectj/AnnotationAsyncExecutionAspect.aj

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 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.
@@ -28,10 +28,10 @@ import org.springframework.scheduling.annotation.Async;
  * <p>This aspect routes methods marked with the {@link Async} annotation as well as methods
  * in classes marked with the same. Any method expected to be routed asynchronously must
  * return either {@code void}, {@link Future}, or a subtype of {@link Future} (in particular,
- * Spring's {@link org.springframework.util.concurrent.ListenableFuture}). This aspect,
+ * {@link java.util.concurrent.CompletableFuture}). This aspect, therefore, will produce a
- * therefore, will produce a compile-time error for methods that violate this constraint
+ * compile-time error for methods that violate this constraint on the return type. If,
- * on the return type. If, however, a class marked with {@code @Async} contains a method
+ * however, a class marked with {@code @Async} contains a method that violates this
- * that violates this constraint, it produces only a warning.
+ * constraint, it produces only a warning.
  *
  * <p>This aspect needs to be injected with an implementation of a task-oriented
  * {@link java.util.concurrent.Executor} to activate it for a specific thread pool,

spring-context/src/main/java/org/springframework/scheduling/annotation/Async.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2022 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.
@@ -35,17 +35,18 @@ import org.springframework.aot.hint.annotation.Reflective;
  * <p>In terms of target method signatures, any parameter types are supported.
  * However, the return type is constrained to either {@code void} or
  * {@link java.util.concurrent.Future}. In the latter case, you may declare the
- * more specific {@link org.springframework.util.concurrent.ListenableFuture} or
+ * more specific {@link java.util.concurrent.CompletableFuture} type which allows
- * {@link java.util.concurrent.CompletableFuture} types which allow for richer
+ * for richer interaction with the asynchronous task and for immediate composition
- * interaction with the asynchronous task and for immediate composition with
+ * with further processing steps.
- * further processing steps.
  *
  * <p>A {@code Future} handle returned from the proxy will be an actual asynchronous
- * {@code Future} that can be used to track the result of the asynchronous method
+ * {@code (Completable)Future} that can be used to track the result of the
- * execution. However, since the target method needs to implement the same signature,
+ * asynchronous method execution. However, since the target method needs to implement
- * it will have to return a temporary {@code Future} handle that just passes a value
+ * the same signature, it will have to return a temporary {@code Future} handle that
- * through: for example, Spring's {@link AsyncResult}, EJB 3.1's {@link jakarta.ejb.AsyncResult},
+ * just passes a value after computation in the execution thread: typically through
- * or {@link java.util.concurrent.CompletableFuture#completedFuture(Object)}.
+ * {@link java.util.concurrent.CompletableFuture#completedFuture(Object)}. The
+ * provided value will be exposed to the caller through the actual asynchronous
+ * {@code Future} handle at runtime.
  *
  * @author Juergen Hoeller
  * @author Chris Beams

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

@@ -80,7 +80,9 @@ import org.springframework.util.concurrent.ListenableFuture;
  * but rather just the hand-off to an execution thread.</b> As a consequence,
  * a {@link ScheduledFuture} handle (for example, from {@link #schedule(Runnable, Instant)})
  * represents that hand-off rather than the actual completion of the provided task
- * (or series of repeated tasks).
+ * (or series of repeated tasks). Also, this scheduler participates in lifecycle
+ * management to a limited degree only, stopping trigger firing and fixed-delay
+ * task execution but not stopping the execution of handed-off 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

spring-core/src/main/java/org/springframework/core/task/SimpleAsyncTaskExecutor.java

@@ -45,6 +45,11 @@ import org.springframework.util.concurrent.ListenableFutureTask;
  * executing a large number of short-lived tasks. Alternatively, on JDK 21,
  * consider setting {@link #setVirtualThreads} to {@code true}.
  *
+ * <p><b>NOTE: This executor does not participate in context-level lifecycle
+ * management.</b> Tasks on handed-off execution threads cannot be centrally
+ * stopped and restarted; if such tight lifecycle management is necessary,
+ * consider a common {@code ThreadPoolTaskExecutor} setup instead.
+ *
  * @author Juergen Hoeller
  * @since 2.0
  * @see #setVirtualThreads