Module org.eclipse.jetty.util

Package org.eclipse.jetty.util.thread

Class QueuedThreadPool

java.lang.Object

org.eclipse.jetty.util.component.AbstractLifeCycle

org.eclipse.jetty.util.component.ContainerLifeCycle

org.eclipse.jetty.util.thread.QueuedThreadPool

All Implemented Interfaces:

Executor, ThreadFactory, Container, Destroyable, Dumpable, Dumpable.DumpableContainer, LifeCycle, ThreadPool, ThreadPool.SizedThreadPool, TryExecutor, VirtualThreads.Configurable

Direct Known Subclasses:

MonitoredQueuedThreadPool

@ManagedObject("A thread pool")
public class QueuedThreadPool
extends ContainerLifeCycle
implements ThreadFactory, ThreadPool.SizedThreadPool, Dumpable, TryExecutor, VirtualThreads.Configurable

A thread pool with a queue of jobs to execute.

The queue of jobs should be unbounded, because critical jobs that have been submitted for execution cannot be rejected due to the queue bound limit. The queue might be temporarily full due to a job submission spike. Furthermore, the same HTTP request may be handled by different jobs, and would be non-optimal to reject a job of a request that is already being handled in favor of a job for a new concurrent request that is not yet handled by the application.

Jetty components that need threads (such as network acceptors and selector) may lease threads from this thread pool using a ThreadPoolBudget; these threads are "active" from the point of view of the thread pool, but not available to run unleased jobs such as processing an HTTP request or a WebSocket frame.

QueuedThreadPool has a ReservedThreadExecutor which leases threads from this pool to be used by the tryExecute(Runnable) method. This allows some key optimizations in the AdaptiveExecutionStrategy. The pool will avoid reserving new threads if there are jobs queued.

QueuedThreadPool has getters to take a snapshot of the following fundamental values:

• threads: the current number of threads. These threads may execute a job (either internal or unleased), or may be ready to run (either idle or reserved). This number may grow or shrink as the thread pool grows or shrinks.
• leasedThreads: the number of threads that may be needed to run internal jobs or be reserved for internal jobs. A pool should always be configured with more threads than the number of leased threads. This number is typically constant after this thread pool is started.
• getCurrentReservedThreads(): the number of threads that have been reserved for #tryExecute(Runnable) jobs.
• getIdleThreads(): the number of threads that are currently waiting for a job.
• getQueueSize(): the number of jobs, queued waiting for a thread.

Given the definitions above, values derived from combinations of fundamental values include:

• getBusyThreads(): the number threads executing tasks.
• getUtilizedThreads(): the number threads executing unleased tasks.

Nested Class Summary

Nested classes/interfaces inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

AbstractLifeCycle.AbstractLifeCycleListener, AbstractLifeCycle.StopException

Nested classes/interfaces inherited from interface org.eclipse.jetty.util.component.Container

Container.InheritedListener, Container.Listener

Nested classes/interfaces inherited from interface org.eclipse.jetty.util.component.Dumpable

Dumpable.DumpableContainer, Dumpable.DumpAppendable

Nested classes/interfaces inherited from interface org.eclipse.jetty.util.component.LifeCycle

LifeCycle.Listener

Nested classes/interfaces inherited from interface org.eclipse.jetty.util.thread.ThreadPool

ThreadPool.SizedThreadPool

Nested classes/interfaces inherited from interface org.eclipse.jetty.util.thread.TryExecutor

TryExecutor.NoTryExecutor

Field Summary

Fields inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

FAILED, STARTED, STARTING, STOPPED, STOPPING

Fields inherited from interface org.eclipse.jetty.util.component.Dumpable

LEGEND

Fields inherited from interface org.eclipse.jetty.util.thread.TryExecutor

NO_TRY

Constructor Summary

Constructors

Constructor	Description
QueuedThreadPool()
QueuedThreadPool(int maxThreads)
QueuedThreadPool(int maxThreads, int minThreads)
QueuedThreadPool(int maxThreads, int minThreads, int idleTimeout)
QueuedThreadPool(int maxThreads, int minThreads, int idleTimeout, int reservedThreads, BlockingQueue<Runnable> queue, ThreadGroup threadGroup)
QueuedThreadPool(int maxThreads, int minThreads, int idleTimeout, int reservedThreads, BlockingQueue<Runnable> queue, ThreadGroup threadGroup, ThreadFactory threadFactory)
QueuedThreadPool(int maxThreads, int minThreads, int idleTimeout, BlockingQueue<Runnable> queue)
QueuedThreadPool(int maxThreads, int minThreads, int idleTimeout, BlockingQueue<Runnable> queue, ThreadGroup threadGroup)
QueuedThreadPool(int maxThreads, int minThreads, BlockingQueue<Runnable> queue)

Method Summary

Modifier and Type	Method	Description
protected void	doStart()	Starts the managed lifecycle beans in the order they were added.
protected void	doStop()	Stops the managed lifecycle beans in the reverse order they were added.
void	dump(Appendable out, String indent)	Dump this object (and children) into an Appendable using the provided indent after any new lines.
String	dumpThread(long id)
protected boolean	evict()	Determines whether to evict the current thread from the pool.
void	execute(Runnable job)
int	getAvailableReservedThreads()	Deprecated, for removal: This API element is subject to removal in a future version. use getCurrentReservedThreads() instead
int	getBusyThreads()	The number of threads executing leased and unleased jobs.
int	getCurrentReservedThreads()
int	getIdleThreads()	The number of idle threads, waiting for tasks to be submitted to execute(Runnable).
int	getIdleTimeout()
int	getLeasedThreads()	The number of threads that are leased, and therefore cannot be used to execute unleased jobs.
int	getLowThreadsThreshold()
int	getMaxAvailableThreads()	Deprecated, for removal: This API element is subject to removal in a future version. The term available can be applied to either idle or reserved threads, but not both.
int	getMaxEvictCount()
int	getMaxLeasedThreads()	Deprecated, for removal: This API element is subject to removal in a future version. use getLeasedThreads()
int	getMaxReservedThreads()
int	getMaxThreads()
int	getMinThreads()
String	getName()
protected BlockingQueue<Runnable>	getQueue()
int	getQueueSize()
int	getReadyThreads()	Deprecated, for removal: This API element is subject to removal in a future version. The combination of idle and reserved threads is essentially meaningless.
int	getReservedThreads()
long	getStopTimeout()
ThreadPoolBudget	getThreadPoolBudget()
int	getThreads()	The number of threads currently started by this thread pool.
int	getThreadsPriority()
double	getUtilizationRate()	The rate between the number of utilized threads and the maximum number of utilizable threads.
int	getUtilizedThreads()	The number of threads executing unleased tasks.
Executor	getVirtualThreadsExecutor()
boolean	interruptThread(long id)
boolean	isDaemon()
boolean	isDetailedDump()
boolean	isLowOnThreads()	Returns whether this thread pool is low on threads.
void	join()	Blocks until the thread pool is LifeCycle stopped.
Thread	newThread(Runnable runnable)
protected void	onJobFailure(Throwable x)
protected void	removeThread(Thread thread)
protected void	runJob(Runnable job)	Runs the given job in the current thread.
void	setDaemon(boolean daemon)
void	setDetailedDump(boolean detailedDump)
void	setIdleTimeout(int idleTimeout)	Set the maximum thread idle time in ms.
void	setLowThreadsThreshold(int lowThreadsThreshold)
void	setMaxEvictCount(int evictCount)	Returns the maximum number of idle threads that are evicted for every idle timeout period, thus shrinking this thread pool towards its minimum number of threads.
void	setMaxThreads(int maxThreads)
void	setMinThreads(int minThreads)
void	setName(String name)	Sets the name of this thread pool, used as a prefix for the thread names.
void	setReservedThreads(int reservedThreads)	Set number of reserved threads or -1 for heuristically determined.
void	setStopTimeout(long stopTimeout)
void	setThreadPoolBudget(ThreadPoolBudget budget)
void	setThreadsPriority(int priority)	Set the priority of the pool threads.
void	setVirtualThreadsExecutor(Executor executor)
protected void	startThread()
String	toString()
boolean	tryExecute(Runnable task)	Attempt to execute a task.

Methods inherited from class org.eclipse.jetty.util.component.ContainerLifeCycle

addBean, addBean, addEventListener, addManaged, contains, destroy, dump, dump, dumpObjects, dumpStdErr, getBean, getBeans, getBeans, getContainedBeans, getContainedBeans, installBean, installBean, isAuto, isManaged, isUnmanaged, manage, removeBean, removeBeans, removeEventListener, setBeans, start, stop, unmanage, updateBean, updateBean, updateBeans, updateBeans

Methods inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

getEventListeners, getState, getState, isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, setEventListeners, start, stop

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.eclipse.jetty.util.component.Container

getCachedBeans, getEventListeners

Methods inherited from interface org.eclipse.jetty.util.component.Dumpable

dump, dumpSelf

Methods inherited from interface org.eclipse.jetty.util.component.Dumpable.DumpableContainer

isDumpable

Methods inherited from interface org.eclipse.jetty.util.VirtualThreads.Configurable

isUseVirtualThreads, setUseVirtualThreads

Constructor Details

QueuedThreadPool

public QueuedThreadPool()

QueuedThreadPool

public QueuedThreadPool(@Name("maxThreads")
 int maxThreads)

QueuedThreadPool

public QueuedThreadPool(@Name("maxThreads")
 int maxThreads,
 @Name("minThreads")
 int minThreads)

QueuedThreadPool

public QueuedThreadPool(@Name("maxThreads")
 int maxThreads,
 @Name("minThreads")
 int minThreads,
 @Name("queue")
 BlockingQueue<Runnable> queue)

QueuedThreadPool

public QueuedThreadPool(@Name("maxThreads")
 int maxThreads,
 @Name("minThreads")
 int minThreads,
 @Name("idleTimeout")
 int idleTimeout)

QueuedThreadPool

public QueuedThreadPool(@Name("maxThreads")
 int maxThreads,
 @Name("minThreads")
 int minThreads,
 @Name("idleTimeout")
 int idleTimeout,
 @Name("queue")
 BlockingQueue<Runnable> queue)

QueuedThreadPool

public QueuedThreadPool(@Name("maxThreads")
 int maxThreads,
 @Name("minThreads")
 int minThreads,
 @Name("idleTimeout")
 int idleTimeout,
 @Name("queue")
 BlockingQueue<Runnable> queue,
 @Name("threadGroup")
 ThreadGroup threadGroup)

QueuedThreadPool

public QueuedThreadPool(@Name("maxThreads")
 int maxThreads,
 @Name("minThreads")
 int minThreads,
 @Name("idleTimeout")
 int idleTimeout,
 @Name("reservedThreads")
 int reservedThreads,
 @Name("queue")
 BlockingQueue<Runnable> queue,
 @Name("threadGroup")
 ThreadGroup threadGroup)

QueuedThreadPool

public QueuedThreadPool(@Name("maxThreads")
 int maxThreads,
 @Name("minThreads")
 int minThreads,
 @Name("idleTimeout")
 int idleTimeout,
 @Name("reservedThreads")
 int reservedThreads,
 @Name("queue")
 BlockingQueue<Runnable> queue,
 @Name("threadGroup")
 ThreadGroup threadGroup,
 @Name("threadFactory")
 ThreadFactory threadFactory)

Method Details

getThreadPoolBudget

public ThreadPoolBudget getThreadPoolBudget()

Specified by:

getThreadPoolBudget in interface ThreadPool.SizedThreadPool

Returns:

a ThreadPoolBudget for this sized thread pool, or null of no ThreadPoolBudget can be returned

setThreadPoolBudget

public void setThreadPoolBudget(ThreadPoolBudget budget)

setStopTimeout

public void setStopTimeout(long stopTimeout)

getStopTimeout

public long getStopTimeout()

doStart

protected void doStart()
                throws Exception

Description copied from class: ContainerLifeCycle

Starts the managed lifecycle beans in the order they were added.

Overrides:

doStart in class ContainerLifeCycle

Throws:

Exception - If there was a problem starting. Will cause a transition to FAILED state

doStop

protected void doStop()
               throws Exception

Description copied from class: ContainerLifeCycle

Stops the managed lifecycle beans in the reverse order they were added.

Overrides:

doStop in class ContainerLifeCycle

Throws:

Exception - If there was a problem stopping. Will cause a transition to FAILED state

getIdleTimeout

@ManagedAttribute("maximum time a thread may be idle in ms")
public int getIdleTimeout()

Returns:

the maximum thread idle time in ms

setIdleTimeout

public void setIdleTimeout(int idleTimeout)

Set the maximum thread idle time in ms.

Threads that are idle for longer than this period may be stopped.

Parameters:

idleTimeout - the maximum thread idle time in ms

getMaxThreads

@ManagedAttribute("maximum number of threads in the pool")
public int getMaxThreads()

Specified by:

getMaxThreads in interface ThreadPool.SizedThreadPool

Returns:

the maximum number of threads

setMaxThreads

public void setMaxThreads(int maxThreads)

Specified by:

setMaxThreads in interface ThreadPool.SizedThreadPool

Parameters:

maxThreads - the maximum number of threads

getMinThreads

@ManagedAttribute("minimum number of threads in the pool")
public int getMinThreads()

Specified by:

getMinThreads in interface ThreadPool.SizedThreadPool

Returns:

the minimum number of threads

setMinThreads

public void setMinThreads(int minThreads)

Specified by:

setMinThreads in interface ThreadPool.SizedThreadPool

Parameters:

minThreads - minimum number of threads

getReservedThreads

@ManagedAttribute("number of configured reserved threads or -1 for heuristic")
public int getReservedThreads()

Returns:

number of reserved threads or -1 for heuristically determined

setReservedThreads

public void setReservedThreads(int reservedThreads)

Set number of reserved threads or -1 for heuristically determined.

Parameters:

reservedThreads - number of reserved threads or -1 for heuristically determined

getName

@ManagedAttribute("name of the thread pool")
public String getName()

Returns:

the name of this thread pool

setName

public void setName(String name)

Sets the name of this thread pool, used as a prefix for the thread names.

Parameters:

name - the name of this thread pool

getThreadsPriority

@ManagedAttribute("priority of threads in the pool")
public int getThreadsPriority()

Returns:

the priority of the pool threads

setThreadsPriority

public void setThreadsPriority(int priority)

Set the priority of the pool threads.

Parameters:

priority - the priority of the pool threads

isDaemon

@ManagedAttribute("thread pool uses daemon threads")
public boolean isDaemon()

Returns:

whether to use daemon threads

See Also:

• Thread.isDaemon()

setDaemon

public void setDaemon(boolean daemon)

Parameters:

daemon - whether to use daemon threads

See Also:

• Thread.setDaemon(boolean)

isDetailedDump

@ManagedAttribute("reports additional details in the dump")
public boolean isDetailedDump()

setDetailedDump

public void setDetailedDump(boolean detailedDump)

getLowThreadsThreshold

@ManagedAttribute("threshold at which the pool is low on threads")
public int getLowThreadsThreshold()

setLowThreadsThreshold

public void setLowThreadsThreshold(int lowThreadsThreshold)

getVirtualThreadsExecutor

public Executor getVirtualThreadsExecutor()

Specified by:

getVirtualThreadsExecutor in interface VirtualThreads.Configurable

Returns:

the Executor to use to execute tasks in virtual threads

setVirtualThreadsExecutor

public void setVirtualThreadsExecutor(Executor executor)

Specified by:

setVirtualThreadsExecutor in interface VirtualThreads.Configurable

Parameters:

executor - the Executor to use to execute tasks in virtual threads

See Also:

• VirtualThreads.areSupported()

setMaxEvictCount

public void setMaxEvictCount(int evictCount)

Returns the maximum number of idle threads that are evicted for every idle timeout period, thus shrinking this thread pool towards its minimum number of threads. The default value is 1.

For example, consider a thread pool with minThread=2, maxThread=20, idleTimeout=5000 and maxEvictCount=3. Let's assume all 20 threads are executing a task, and they all finish their own tasks at the same time and no more tasks are submitted; then, 3 threads will be evicted, while the other 17 will wait another idle timeout; then another 3 threads will be evicted, and so on until minThreads=2 will be reached.

Parameters:

evictCount - the maximum number of idle threads to evict in one idle timeout period

getMaxEvictCount

@ManagedAttribute("maximum number of idle threads to evict in one idle timeout period")
public int getMaxEvictCount()

Returns:

the maximum number of idle threads to evict in one idle timeout period

getQueueSize

@ManagedAttribute("size of the job queue")
public int getQueueSize()

Returns:

the number of jobs in the queue waiting for a thread

getMaxReservedThreads

@ManagedAttribute("maximum number (capacity) of reserved threads")
public int getMaxReservedThreads()

Returns:

the maximum number (capacity) of reserved threads that have actually been reserved. The value will always be less than or equal to getReservedThreads().

See Also:

• ReservedThreadExecutor.getCapacity()

getCurrentReservedThreads

@ManagedAttribute("number of current reserved threads")
public int getCurrentReservedThreads()

Returns:

the number of available reserved threads that are currently reserved

See Also:

• ReservedThreadExecutor.getAvailable()

getAvailableReservedThreads

@Deprecated(forRemoval=true,
            since="12.1.0")
@ManagedAttribute("number of available reserved threads")
public int getAvailableReservedThreads()

Deprecated, for removal: This API element is subject to removal in a future version.

use getCurrentReservedThreads() instead

Returns:

the number of available reserved threads that are currently reserved

See Also:

• getCurrentReservedThreads()

getThreads

@ManagedAttribute("number of threads in the pool")
public int getThreads()

The number of threads currently started by this thread pool.

This value includes threads that have been leased threads, idle threads, reserved threads and threads that are executing unleased jobs.

Specified by:

getThreads in interface ThreadPool

Returns:

the number of threads currently known to the pool

See Also:

• getIdleThreads()
• getCurrentReservedThreads()

getReadyThreads

@Deprecated(forRemoval=true,
            since="12.1.0")
@ManagedAttribute("number of threads ready to execute unleased jobs")
public int getReadyThreads()

Deprecated, for removal: This API element is subject to removal in a future version.

The combination of idle and reserved threads is essentially meaningless.

The number of threads ready to execute unleased jobs.

Returns:

the number of threads ready to execute unleased jobs

See Also:

• getThreads()
• getLeasedThreads()
• getUtilizedThreads()

getLeasedThreads

@ManagedAttribute("number of threads leased for use by jetty components")
public int getLeasedThreads()

The number of threads that are leased, and therefore cannot be used to execute unleased jobs.

Returns:

the number of threads currently used by internal components

See Also:

• getThreads()
• getReadyThreads()

getMaxLeasedThreads

@Deprecated(forRemoval=true,
            since="12.1.0")
@ManagedAttribute("maximum number of threads leased to internal components")
public int getMaxLeasedThreads()

Deprecated, for removal: This API element is subject to removal in a future version.

use getLeasedThreads()

The maximum number of threads that are leased to internal components, as some component may allocate its threads lazily.

Returns:

the maximum number of threads leased by internal components

See Also:

• getLeasedThreads()

getIdleThreads

@ManagedAttribute("number of idle threads but not reserved")
public int getIdleThreads()

The number of idle threads, waiting for tasks to be submitted to execute(Runnable).

Note that getCurrentReservedThreads() are not counted as idle threads.

Specified by:

getIdleThreads in interface ThreadPool

Returns:

the number of idle threads

getBusyThreads

@ManagedAttribute("number of threads executing internal and unleased jobs")
public int getBusyThreads()

The number of threads executing leased and unleased jobs.

Prefer getUtilizedThreads() for a representation of "threads executing unleased jobs".

Returns:

the number of threads executing internal and unleased jobs

See Also:

• getUtilizedThreads()

getUtilizedThreads

@ManagedAttribute("number of threads executing unleased jobs")
public int getUtilizedThreads()

The number of threads executing unleased tasks.

Returns:

the number of threads executing unleased tasks

See Also:

• getReadyThreads()

getMaxAvailableThreads

@ManagedAttribute("maximum number of threads available to run unleased jobs (deprecated")
@Deprecated(forRemoval=true,
            since="12.1.0")
public int getMaxAvailableThreads()

Deprecated, for removal: This API element is subject to removal in a future version.

The term available can be applied to either idle or reserved threads, but not both. Use getCurrentReservedThreads() or getIdleThreads() instead.

The maximum number of threads available to run unleased jobs.

Returns:

the maximum number of threads available to run unleased jobs

getUtilizationRate

@ManagedAttribute("utilization rate of threads executing unleased jobs")
public double getUtilizationRate()

The rate between the number of utilized threads and the maximum number of utilizable threads.

A value of 0.0D means that the thread pool is not utilized, while a value of 1.0D means that the thread pool is fully utilized to execute unleased jobs.

Returns:

the utilization rate of threads executing unleased jobs

isLowOnThreads

@ManagedAttribute(value="thread pool is low on threads",
                  readonly=true)
public boolean isLowOnThreads()

Returns whether this thread pool is low on threads.

The current formula is:

 maxThreads - threads + idleThreads - queueSize <= lowThreadsThreshold
 

Specified by:

isLowOnThreads in interface ThreadPool

Returns:

whether the pool is low on threads

See Also:

• getLowThreadsThreshold()

execute

public void execute(Runnable job)

Specified by:

execute in interface Executor

Specified by:

execute in interface TryExecutor

tryExecute

public boolean tryExecute(Runnable task)

Description copied from interface: TryExecutor

Attempt to execute a task.

Specified by:

tryExecute in interface TryExecutor

Parameters:

task - The task to be executed

Returns:

True IFF the task has been given directly to a thread to execute. The task cannot be queued pending the later availability of a Thread.

join

public void join()
          throws InterruptedException

Blocks until the thread pool is LifeCycle stopped.

Specified by:

join in interface ThreadPool

Throws:

InterruptedException - if thread was interrupted

startThread

protected void startThread()

newThread

public Thread newThread(Runnable runnable)

Specified by:

newThread in interface ThreadFactory

removeThread

protected void removeThread(Thread thread)

dump

public void dump(Appendable out,
 String indent)
          throws IOException

Description copied from interface: Dumpable

Dump this object (and children) into an Appendable using the provided indent after any new lines. The indent should not be applied to the first object dumped.

Specified by:

dump in interface Dumpable

Overrides:

dump in class ContainerLifeCycle

Parameters:

out - The appendable to dump to

indent - The indent to apply after any new lines.

Throws:

IOException - if unable to write to Appendable

runJob

protected void runJob(Runnable job)

Runs the given job in the current thread.

Subclasses may override to perform pre/post actions before/after the job is run.

Parameters:

job - the job to run

onJobFailure

protected void onJobFailure(Throwable x)

evict

protected boolean evict()

Determines whether to evict the current thread from the pool.

Returns:

whether the current thread should be evicted

getQueue

protected BlockingQueue<Runnable> getQueue()

Returns:

the job queue

interruptThread

@ManagedOperation("interrupts a pool thread")
public boolean interruptThread(@Name("id")
 long id)

Parameters:

id - the thread ID to interrupt.

Returns:

true if the thread was found and interrupted.

dumpThread

@ManagedOperation("dumps a pool thread stack")
public String dumpThread(@Name("id")
 long id)

Parameters:

id - the thread ID to interrupt.

Returns:

the stack frames dump

toString

public String toString()

Overrides:

toString in class AbstractLifeCycle