async-execution · git:20261110.1bdf531 · 2026-11-10 · sha256 36a689e18196cc46
async-execution git:20261110.1bdf531A
Immutable. This exact content never changes and is served at /api/v1/blob/36a689e18196cc46.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_nck2ppj6p43rlzdp/36a689e18196cc464f413b006d10aeada06b76ac429c53bef07f94317b423d7c.json
Then /plugin install async-execution@markdownregistry-nck2ppj6p43rlzdp in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
--- 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)