Package org.springframework.core.task

# Class SimpleAsyncTaskExecutor

java.lang.Object
org.springframework.util.CustomizableThreadCreator
org.springframework.core.task.SimpleAsyncTaskExecutor

All Implemented Interfaces:
  `Serializable`, `AutoCloseable`, `Executor`, `AsyncListenableTaskExecutor`, `AsyncTaskExecutor`, `TaskExecutor`

public class SimpleAsyncTaskExecutor extends CustomizableThreadCreator implements AsyncListenableTaskExecutor, Serializable, AutoCloseable
`TaskExecutor` implementation that fires up a new Thread for each task. Provides a `virtual threads` option on JDK 21+.

Supports a graceful shutdown through `setTaskTerminationTimeout(long)`, at the expense of task tracking overhead per execution thread at runtime. Supports limiting concurrent threads through `setConcurrencyLimit(int)`; by default, the number of concurrent task executions is unlimited.

NOTE: This implementation does not reuse threads! Consider a thread-pooling TaskExecutor implementation instead, in particular for executing a large number of short-lived tasks. Alternatively, on JDK 21, consider setting `setVirtualThreads(boolean)` to `true`.

NOTE: This executor does not participate in context-level lifecycle management. Tasks on handed-off execution threads cannot be centrally stopped and restarted; if such tight lifecycle management is necessary, consider a common `ThreadPoolTaskExecutor` setup instead.

Since:
  2.0
Author:
  Juergen Hoeller
See Also:
  - `setVirtualThreads(boolean)`
  - `setTaskTerminationTimeout(long)`
  - `setConcurrencyLimit(int)`
  - `org.springframework.scheduling.concurrent.SimpleAsyncTaskScheduler`
  - `org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor`
  - Serialized Form

## Field Summary

Fields
Modifier and Type
Field
Description
`static final int`
`NO_CONCURRENCY`
Switch concurrency 'off': that is, don't allow any concurrent invocations.
`static final int`
`UNBOUNDED_CONCURRENCY`
Permit any number of concurrent invocations: that is, don't throttle concurrency.

### Fields inherited from interface org.springframework.core.task.AsyncTaskExecutor

`TIMEOUT_IMMEDIATE, TIMEOUT_INDEFINITE`

## Constructor Summary

Constructors
Constructor
Description
`SimpleAsyncTaskExecutor()`
Create a new SimpleAsyncTaskExecutor with default thread name prefix.
`SimpleAsyncTaskExecutor(String threadNamePrefix)`
Create a new SimpleAsyncTaskExecutor with the given thread name prefix.
`SimpleAsyncTaskExecutor(ThreadFactory threadFactory)`
Create a new SimpleAsyncTaskExecutor with the given external thread factory.

## Method Summary

Modifier and Type
Method
Description
`void`
`close()`
This close method tracks the termination of active threads if a concrete `task termination timeout` has been set.
`protected void`
`doExecute(Runnable task)`
Template method for the actual execution of a task.
`void`
`execute(Runnable task)`
Executes the given task, within a concurrency throttle if configured (through the superclass's settings).
`void`
`execute(Runnable task, long startTimeout)`
Deprecated.
`final int`
`getConcurrencyLimit()`
Return the maximum number of parallel task executions allowed.
`final ThreadFactory`
`getThreadFactory()`
Return the external factory to use for creating new Threads, if any.
`boolean`
`isActive()`
Return whether this executor is still active, i.e.
`final boolean`
`isThrottleActive()`
Return whether the concurrency throttle is currently active.
`protected Thread`
`newThread(Runnable task)`
Create a new Thread for the given task.
`void`
`setCancelRemainingTasksOnClose(boolean cancelRemainingTasksOnClose)`
Specify whether to cancel remaining tasks on close: that is, whether to interrupt any active threads at the time of the `close()` call.
`void`
`setConcurrencyLimit(int concurrencyLimit)`
Set the maximum number of parallel task executions allowed.
`void`
`setRejectTasksWhenLimitReached(boolean rejectTasksWhenLimitReached)`
Specify whether to reject tasks when the concurrency limit has been reached, throwing `TaskRejectedException` (which extends the common `RejectedExecutionException`) on any further execution attempts.
`void`
`setTaskDecorator(TaskDecorator taskDecorator)`
Specify a custom `TaskDecorator` to be applied to any `Runnable` about to be executed.
`void`
`setTaskTerminationTimeout(long timeout)`
Specify a timeout (in milliseconds) for task termination when closing this executor.
`void`
`setThreadFactory(ThreadFactory threadFactory)`
Specify an external factory to use for creating new Threads, instead of relying on the local properties of this executor.
`void`
`setVirtualThreads(boolean virtual)`
Switch this executor to virtual threads.
`Future<?>`
`submit(Runnable task)`
Submit a Runnable task for execution, receiving a Future representing that task.
`<T> Future<T>`
`submit(Callable<T> task)`
Submit a Callable task for execution, receiving a Future representing that task.
`ListenableFuture<?>`
`submitListenable(Runnable task)`
Submit a `Runnable` task for execution, receiving a `ListenableFuture` representing that task.
`<T> ListenableFuture<T>`
`submitListenable(Callable<T> task)`
Submit a `Callable` task for execution, receiving a `ListenableFuture` representing that task.

### Methods inherited from class org.springframework.util.CustomizableThreadCreator

`createThread, getDefaultThreadNamePrefix, getThreadGroup, getThreadNamePrefix, getThreadPriority, isDaemon, nextThreadName, setDaemon, setThreadGroup, setThreadGroupName, setThreadNamePrefix, setThreadPriority`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Methods inherited from interface org.springframework.core.task.AsyncTaskExecutor

`submitCompletable, submitCompletable`

## Field Details

### UNBOUNDED_CONCURRENCY

public static final int UNBOUNDED_CONCURRENCY
Permit any number of concurrent invocations: that is, don't throttle concurrency.

See Also:
  - `ConcurrencyThrottleSupport.UNBOUNDED_CONCURRENCY`
  - Constant Field Values

### NO_CONCURRENCY

public static final int NO_CONCURRENCY
Switch concurrency 'off': that is, don't allow any concurrent invocations.

See Also:
  - `ConcurrencyThrottleSupport.NO_CONCURRENCY`
  - Constant Field Values

## Constructor Details

### SimpleAsyncTaskExecutor

public SimpleAsyncTaskExecutor()
Create a new SimpleAsyncTaskExecutor with default thread name prefix.

### SimpleAsyncTaskExecutor

public SimpleAsyncTaskExecutor(String threadNamePrefix)
Create a new SimpleAsyncTaskExecutor with the given thread name prefix.

Parameters:
  `threadNamePrefix` - the prefix to use for the names of newly created threads

### SimpleAsyncTaskExecutor

public SimpleAsyncTaskExecutor(ThreadFactory threadFactory)
Create a new SimpleAsyncTaskExecutor with the given external thread factory.

Parameters:
  `threadFactory` - the factory to use for creating new Threads

## Method Details

### setVirtualThreads

public void setVirtualThreads(boolean virtual)
Switch this executor to virtual threads. Requires Java 21 or higher.

The default is `false`, indicating platform threads. Set this flag to `true` in order to create virtual threads instead.

Since:
  6.1

### setThreadFactory

public void setThreadFactory(@Nullable ThreadFactory threadFactory)
Specify an external factory to use for creating new Threads, instead of relying on the local properties of this executor.

You may specify an inner ThreadFactory bean or also a ThreadFactory reference obtained from JNDI (on a Jakarta EE server) or some other lookup mechanism.

See Also:
  - `CustomizableThreadCreator.setThreadNamePrefix(java.lang.String)`
  - `CustomizableThreadCreator.setThreadPriority(int)`

### getThreadFactory

@Nullable public final ThreadFactory getThreadFactory()
Return the external factory to use for creating new Threads, if any.

### setTaskDecorator

public void setTaskDecorator(TaskDecorator taskDecorator)
Specify a custom `TaskDecorator` to be applied to any `Runnable` about to be executed.

Note that such a decorator is not necessarily being applied to the user-supplied `Runnable`/`Callable` but rather to the actual execution callback (which may be a wrapper around the user-supplied task).

The primary use case is to set some execution context around the task's invocation, or to provide some monitoring/statistics for task execution.

NOTE: Exception handling in `TaskDecorator` implementations is limited to plain `Runnable` execution via `execute` calls. In case of `#submit` calls, the exposed `Runnable` will be a `FutureTask` which does not propagate any exceptions; you might have to cast it and call `Future#get` to evaluate exceptions.

Since:
  4.3

### setTaskTerminationTimeout

public void setTaskTerminationTimeout(long timeout)
Specify a timeout (in milliseconds) for task termination when closing this executor. The default is 0, not waiting for task termination at all.

Note that a concrete >0 timeout specified here will lead to the wrapping of every submitted task into a task-tracking runnable which involves considerable overhead in case of a high number of tasks. However, for a modest level of submissions with longer-running tasks, this is feasible in order to arrive at a graceful shutdown.

Note that `SimpleAsyncTaskExecutor` does not participate in a coordinated lifecycle stop but rather just awaits task termination on `close()`.

Parameters:
  `timeout` - the timeout in milliseconds
Since:
  6.1
See Also:
  - `close()`
  - `setCancelRemainingTasksOnClose(boolean)`
  - `org.springframework.scheduling.concurrent.ExecutorConfigurationSupport#setAwaitTerminationMillis`

### setCancelRemainingTasksOnClose

public void setCancelRemainingTasksOnClose(boolean cancelRemainingTasksOnClose)
Specify whether to cancel remaining tasks on close: that is, whether to interrupt any active threads at the time of the `close()` call.

The default is `false`, not tracking active threads at all or just interrupting any remaining threads that still have not finished after the specified `taskTerminationTimeout`. Switch this to `true` for immediate interruption on close, either in combination with a subsequent termination timeout or without any waiting at all, depending on whether a `taskTerminationTimeout` has been specified as well.

Since:
  6.2.11
See Also:
  - `close()`
  - `setTaskTerminationTimeout(long)`
  - `org.springframework.scheduling.concurrent.ExecutorConfigurationSupport#setWaitForTasksToCompleteOnShutdown`

### setRejectTasksWhenLimitReached

public void setRejectTasksWhenLimitReached(boolean rejectTasksWhenLimitReached)
Specify whether to reject tasks when the concurrency limit has been reached, throwing `TaskRejectedException` (which extends the common `RejectedExecutionException`) on any further execution attempts.

The default is `false`, blocking the caller until the submission can be accepted. Switch this to `true` for immediate rejection instead.

Since:
  6.2.6
See Also:
  - `setConcurrencyLimit(int)`

### setConcurrencyLimit

public void setConcurrencyLimit(int concurrencyLimit)
Set the maximum number of parallel task executions allowed. The default of -1 indicates no concurrency limit at all.

This is the equivalent of a maximum pool size in a thread pool, preventing temporary overload of the thread management system. However, in contrast to a thread pool with a managed task queue, this executor will block the submitter until the task can be accepted when the configured concurrency limit has been reached. If you prefer queue-based task hand-offs without such blocking, consider using a `ThreadPoolTaskExecutor` instead.

See Also:
  - `UNBOUNDED_CONCURRENCY`
  - `org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor#setMaxPoolSize`

### getConcurrencyLimit

public final int getConcurrencyLimit()
Return the maximum number of parallel task executions allowed.

### isThrottleActive

public final boolean isThrottleActive()
Return whether the concurrency throttle is currently active.

Returns:
  `true` if the concurrency limit for this instance is active
See Also:
  - `getConcurrencyLimit()`
  - `setConcurrencyLimit(int)`

### isActive

public boolean isActive()
Return whether this executor is still active, i.e. not closed yet, and therefore accepts further task submissions. Otherwise, it is either in the task termination phase or entirely shut down already.

Since:
  6.1
See Also:
  - `setTaskTerminationTimeout(long)`
  - `close()`

### execute

public void execute(Runnable task)
Executes the given task, within a concurrency throttle if configured (through the superclass's settings).

Specified by:
  `execute` in interface `Executor`
Specified by:
  `execute` in interface `TaskExecutor`
Parameters:
  `task` - the `Runnable` to execute (never `null`)
See Also:
  - `doExecute(Runnable)`

### execute

@Deprecated(since="5.3.16") public void execute(Runnable task, long startTimeout)
Deprecated.
Executes the given task, within a concurrency throttle if configured (through the superclass's settings).

Executes urgent tasks (with 'immediate' timeout) directly, bypassing the concurrency throttle (if active). All other tasks are subject to throttling.

Specified by:
  `execute` in interface `AsyncTaskExecutor`
Parameters:
  `task` - the `Runnable` to execute (never `null`)
  `startTimeout` - the time duration (milliseconds) within which the task is supposed to start. This is intended as a hint to the executor, allowing for preferred handling of immediate tasks. Typical values are `AsyncTaskExecutor.TIMEOUT_IMMEDIATE` or `AsyncTaskExecutor.TIMEOUT_INDEFINITE` (the default as used by `TaskExecutor.execute(Runnable)`).
See Also:
  - `AsyncTaskExecutor.TIMEOUT_IMMEDIATE`
  - `doExecute(Runnable)`

### submit

public Future<?> submit(Runnable task)
Description copied from interface: `AsyncTaskExecutor`
Submit a Runnable task for execution, receiving a Future representing that task. The Future will return a `null` result upon completion.

As of 6.1, this method comes with a default implementation that delegates to `TaskExecutor.execute(Runnable)`.

Specified by:
  `submit` in interface `AsyncTaskExecutor`
Parameters:
  `task` - the `Runnable` to execute (never `null`)
Returns:
  a Future representing pending completion of the task

### submit

public <T> Future<T> submit(Callable<T> task)
Description copied from interface: `AsyncTaskExecutor`
Submit a Callable task for execution, receiving a Future representing that task. The Future will return the Callable's result upon completion.

As of 6.1, this method comes with a default implementation that delegates to `TaskExecutor.execute(Runnable)`.

Specified by:
  `submit` in interface `AsyncTaskExecutor`
Parameters:
  `task` - the `Callable` to execute (never `null`)
Returns:
  a Future representing pending completion of the task

### submitListenable

public ListenableFuture<?> submitListenable(Runnable task)
Description copied from interface: `AsyncListenableTaskExecutor`
Submit a `Runnable` task for execution, receiving a `ListenableFuture` representing that task. The Future will return a `null` result upon completion.

Specified by:
  `submitListenable` in interface `AsyncListenableTaskExecutor`
Parameters:
  `task` - the `Runnable` to execute (never `null`)
Returns:
  a `ListenableFuture` representing pending completion of the task

### submitListenable

public <T> ListenableFuture<T> submitListenable(Callable<T> task)
Description copied from interface: `AsyncListenableTaskExecutor`
Submit a `Callable` task for execution, receiving a `ListenableFuture` representing that task. The Future will return the Callable's result upon completion.

Specified by:
  `submitListenable` in interface `AsyncListenableTaskExecutor`
Parameters:
  `task` - the `Callable` to execute (never `null`)
Returns:
  a `ListenableFuture` representing pending completion of the task

### doExecute

protected void doExecute(Runnable task)
Template method for the actual execution of a task.

The default implementation creates a new Thread and starts it.

Parameters:
  `task` - the Runnable to execute
See Also:
  - `newThread(java.lang.Runnable)`
  - `Thread.start()`

### newThread

protected Thread newThread(Runnable task)
Create a new Thread for the given task.

Parameters:
  `task` - the Runnable to create a Thread for
Returns:
  the new Thread instance
Since:
  6.1
See Also:
  - `setVirtualThreads(boolean)`
  - `setThreadFactory(java.util.concurrent.ThreadFactory)`
  - `CustomizableThreadCreator.createThread(java.lang.Runnable)`

### close

public void close()
This close method tracks the termination of active threads if a concrete `task termination timeout` has been set. Otherwise, it is not necessary to close this executor.

Specified by:
  `close` in interface `AutoCloseable`
Since:
  6.1