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.

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 transient jobs such as processing an HTTP request or a WebSocket frame.

QueuedThreadPool has a ReservedThreadExecutor which leases threads from this pool, but makes them available as if they are "idle" threads.

QueuedThreadPool therefore has the following fundamental values:

• threads: the current number of threads. These threads may execute a job (either internal or transient), or may be ready to run (either idle or reserved). This number may grow or shrink as the thread pool grows or shrinks.
• readyThreads: the current number of threads that are ready to run transient jobs. This number may grow or shrink as the thread pool grows or shrinks.
• leasedThreads: the number of threads that run internal jobs. This number is typically constant after this thread pool is started.

Given the definitions above, the most interesting definitions are:

• threads = readyThreads + leasedThreads + utilizedThreads
• readyThreads = idleThreads + availableReservedThreads
• maxAvailableThreads = maxThreads - leasedThreads
• utilizationRate = utilizedThreads / maxAvailableThreads

Other definitions, typically less interesting because they take into account threads that execute internal jobs, or because they don't take into account available reserved threads (that are essentially ready to execute transient jobs), are:

• busyThreads = utilizedThreads + leasedThreads
• idleThreads = readyThreads - availableReservedThreads

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

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

KEY

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()
int	getBusyThreads()	The number of threads executing internal and transient jobs.
int	getIdleThreads()	The number of idle threads, but without including reserved threads.
int	getIdleTimeout()
int	getLeasedThreads()	The fundamental value that represents the number of threads that are leased to internal components, and therefore cannot be used to execute transient jobs.
int	getLowThreadsThreshold()
int	getMaxAvailableThreads()	The maximum number of threads available to run transient jobs.
int	getMaxEvictCount()
int	getMaxLeasedThreads()	The maximum number of threads that are leased to internal components, as some component may allocate its threads lazily.
int	getMaxReservedThreads()
int	getMaxThreads()
int	getMinThreads()
String	getName()
protected BlockingQueue<Runnable>	getQueue()
int	getQueueSize()
int	getReadyThreads()	The fundamental value that represents the number of threads ready to execute transient jobs.
int	getReservedThreads()
long	getStopTimeout()
ThreadPoolBudget	getThreadPoolBudget()
int	getThreads()	The fundamental value that represents the number of threads currently known 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 transient jobs.
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	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)
void	setStopTimeout(long stopTimeout)
void	setThreadPoolBudget(ThreadPoolBudget budget)
void	setThreadsPriority(int priority)
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, 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)

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 the 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 the 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)

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

See Also:

• ReservedThreadExecutor.getCapacity()

getAvailableReservedThreads

@ManagedAttribute("number of available reserved threads")
public int getAvailableReservedThreads()

Returns:

the number of available reserved threads

See Also:

• ReservedThreadExecutor.getAvailable()

getThreads

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

The fundamental value that represents the number of threads currently known by this thread pool.

This value includes threads that have been leased to internal components, idle threads, reserved threads and threads that are executing transient jobs.

Specified by:

getThreads in interface ThreadPool

Returns:

the number of threads currently known to the pool

See Also:

• getReadyThreads()
• getLeasedThreads()

getReadyThreads

@ManagedAttribute("number of threads ready to execute transient jobs")
public int getReadyThreads()

The fundamental value that represents the number of threads ready to execute transient jobs.

Returns:

the number of threads ready to execute transient jobs

See Also:

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

getLeasedThreads

@ManagedAttribute("number of threads used by internal components")
public int getLeasedThreads()

The fundamental value that represents the number of threads that are leased to internal components, and therefore cannot be used to execute transient jobs.

Returns:

the number of threads currently used by internal components

See Also:

• getThreads()
• getReadyThreads()

getMaxLeasedThreads

@ManagedAttribute("maximum number of threads leased to internal components")
public int getMaxLeasedThreads()

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, but without including reserved threads.

Prefer getReadyThreads() for a better representation of "threads ready to execute transient jobs".

Specified by:

getIdleThreads in interface ThreadPool

Returns:

the number of idle threads but not reserved

See Also:

• getReadyThreads()

getBusyThreads

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

The number of threads executing internal and transient jobs.

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

Returns:

the number of threads executing internal and transient jobs

See Also:

• getUtilizedThreads()

getUtilizedThreads

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

The number of threads executing transient jobs.

Returns:

the number of threads executing transient jobs

See Also:

• getReadyThreads()

getMaxAvailableThreads

@ManagedAttribute("maximum number of threads available to run transient jobs")
public int getMaxAvailableThreads()

The maximum number of threads available to run transient jobs.

Returns:

the maximum number of threads available to run transient jobs

getUtilizationRate

@ManagedAttribute("utilization rate of threads executing transient 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 transient jobs.

Returns:

the utilization rate of threads executing transient 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 + readyThreads - 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

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