/async-execution

name: async-execution
description: >
  Use when adding or debugging Spring @Async work, executor saturation, asynchronous failures or lost thread context. Not a substitute for durable jobs or reactive pipelines.

Async Execution

Spring Boot 3 baseline

Use Framework 6 APIs and the project's Boot BOM. The shipped examples compile on Java 17. Boot 3.2+ can opt into virtual threads on Java 21; do not assume this on earlier Boot 3 releases. Check the exact minor before copying newer task-execution properties.

Choose the execution boundary

First decide whether losing work on process exit is acceptable. In-memory async work is not a durable queue. Required notifications, payments and accepted background jobs need persisted intent plus recovery, not just an AFTER_COMMIT listener or an HTTP 202 response. Keep an existing broker or job framework when it already owns this contract.

Enable async interception once and call a separate Spring bean through its proxy. A same-class call does not become asynchronous. Use a named executor and return CompletableFuture when the caller must observe failure. A void method needs an AsyncUncaughtExceptionHandler; the caller cannot catch its later failure. Rejection can happen synchronously during submission.

See [the bounded executor](templates/ReportExecutorConfiguration.java) and [the worker](templates/ReportTasks.java). Sizes are example budgets, not universal defaults. [Good usage](examples/good-report-call.java) separates rejected submissions from failed work; [bad usage](examples/bad-self-invocation.java) hides both the execution and capacity problems.

Capacity and lifecycle

Bound threads and queued work against downstream capacity and latency targets. A large queue can hide overload and delay growth beyond the core pool. Define a visible rejection outcome; do not silently discard required work. CallerRunsPolicy can move blocking work onto an HTTP or event-loop thread, so it is not a universal backpressure fix.

A custom Executor can change Boot auto-configuration. Preserve the application's existing applicationTaskExecutor and MVC/WebFlux integration; do not paste the sample configuration over it. The sample explicitly selects reportExecutor and only covers that worker. Virtual threads do not increase database connections or remote quotas: bound outstanding work even without a platform-thread pool. Configure I/O timeouts and bounded shutdown separately. Future cancellation/timeout is not proof that an external operation stopped.

State and transactions

Pass immutable IDs or snapshots, not request objects, managed entities or lazy collections. The caller's thread-bound transaction does not move with the task. Put any worker transaction on a separate proxied service and load its state there. Starting async work before commit can observe missing data; after-commit dispatch still has a crash-loss window.

Tenant, MDC and security state need deliberate propagation and cleanup. Capture only required, trusted context; restore prior worker state in finally. Use Spring Security's delegating executor support when the operation must run with the submitting security context. Do not use inheritable thread locals as a pool-wide tenant or authentication strategy.

Verification

Test via the actual proxy: worker thread selection, failed futures, saturation rejection and shutdown. Use latches with deadlines, not sleep-based assumptions. Test context cleanup with successive users on the same worker and database visibility at the commit boundary. Report which tests were actually run; the provided fixture does not certify durable delivery.

Gotchas

• Agent calls its own @Async method - invoke a separate managed bean through the proxy.
• Agent calls supplyAsync without an executor inside the worker - avoid a second common-pool hop.
• Agent treats an unbounded queue as overload protection - set and test an explicit capacity budget.
• Agent catches only future failures - handle synchronous task rejection too.
• Agent assumes AFTER_COMMIT plus async guarantees delivery - persist required work for recovery.
• Agent copies tenant or security state without cleanup - prevent leakage between pooled tasks.

Official sources

• [Boot 3 task execution](https://docs.spring.io/spring-boot/3.5/reference/features/task-execution-and-scheduling.html)
• [Framework 6 scheduling and async interception](https://docs.spring.io/spring-framework/reference/6.2/integration/scheduling.html)
• [Async return types and executor selection](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/scheduling/annotation/Async.html)
• [ThreadPoolTaskExecutor capacity](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/scheduling/concurrent/ThreadPoolTaskExecutor.html)
• [Spring Security concurrency support](https://docs.spring.io/spring-security/reference/features/integrations/concurrency.html)
• [Transaction-bound events](https://docs.spring.io/spring-framework/reference/data-access/transaction/event.html)