org.threadly.concurrent

Class CentralThreadlyPool

java.lang.Object

org.threadly.concurrent.CentralThreadlyPool

public class CentralThreadlyPool
extends java.lang.Object

Threadly's centrally provided pool manager. This class is designed to avoid needing to manage the thread pool lifecycle throughout your application. Instead of needing to think about how to manage a pools lifecycle you can instead just describe the needs of the tasks to be submitted.

Internally this will delegate to a central or otherwise specific pool for your needs, while minimizing thread creation / churn as much as possible. In addition the returned pools do not need to be shutdown, but instead you can allow to be garbage collected as you are done with them. There is no need to be concerned about allowing a returned pool to be garbage collected before any submitted / scheduled / recurring tasks have completed.

Most users will find themselves sticking to the simple pools this provides:

• computationPool() for doing CPU bound computational tasks
• lowPriorityPool() for doing low priority maintenance tasks
• singleThreadPool() as a way to gain access to an efficient priority respected single thread pool
• threadPool(int) and threadPool(TaskPriority, int) to have a multi-threaded pool
• isolatedTaskPool() For single / isolated tasks against the central pool

More advanced users can attempt to further reduce thread chun by adding general purpose threads with increaseGenericThreads(int). You can then use singleThreadPool(boolean) with false to just depend on these general processing threads. And in addition rangedThreadPool(int, int) and rangedThreadPool(TaskPriority, int, int) in order to specify how when guaranteed threads need to be provided, and how much of the general processing threads the pool can take advantage of.

Stats (like SchedulerService.getActiveTaskCount() and SchedulerService.getQueuedTaskCount(), etc) from provided pools will always be representative of the entire central pool rather than just relative to the returned pool.

Since:

5.7

Constructor Summary

Constructors

Constructor and Description
CentralThreadlyPool()

Method Summary

Modifier and Type	Method and Description
static SchedulerService	computationPool() Thread pool well suited for running CPU intensive computations on the tasks thread.
static SchedulerService	computationPool(java.lang.String threadName) Thread pool well suited for running CPU intensive computations on the tasks thread.
static int	getGenericThreadCount() This reports the number of threads currently available for processing across all pools where the max thread count is > the guaranteed thread count.
static void	increaseGenericThreads(int count) Increase available threads threads that can be shared across pools.
static SchedulerService	isolatedTaskPool() This returns a thread pool which is designed for an "isolated" task.
static SchedulerService	isolatedTaskPool(java.lang.String threadName) This returns a thread pool which is designed for an "isolated" task.
static SchedulerService	lowPriorityPool() Low priority pool for scheduling cleanup or otherwise tasks which could be significantly delayed.
static SchedulerService	lowPriorityPool(java.lang.String threadName) Low priority pool for scheduling cleanup or otherwise tasks which could be significantly delayed.
static PrioritySchedulerService	lowPrioritySingleThreadPool() Low priority pool for scheduling cleanup or otherwise tasks which could be significantly delayed.
static PrioritySchedulerService	lowPrioritySingleThreadPool(java.lang.String threadName) Low priority pool for scheduling cleanup or otherwise tasks which could be significantly delayed.
static SchedulerService	rangedThreadPool(int guaranteedThreads, int maxThreads) Requests a pool with a given range of threads.
static SchedulerService	rangedThreadPool(int guaranteedThreads, int maxThreads, java.lang.String threadName) Requests a pool with a given range of threads.
static SchedulerService	rangedThreadPool(TaskPriority priority, int guaranteedThreads, int maxThreads) Requests a pool with a given range of threads.
static SchedulerService	rangedThreadPool(TaskPriority priority, int guaranteedThreads, int maxThreads, java.lang.String threadName) Requests a pool with a given range of threads.
static PrioritySchedulerService	singleThreadPool() Return a single threaded pool.
static PrioritySchedulerService	singleThreadPool(boolean threadGuaranteed) Return a single threaded pool.
static PrioritySchedulerService	singleThreadPool(boolean threadGuaranteed, java.lang.String threadName) Return a single threaded pool.
static PrioritySchedulerService	singleThreadPool(boolean threadGuaranteed, java.lang.String threadName, int threadPriority) Return a single threaded pool.
static PrioritySchedulerService	singleThreadPool(java.lang.String threadName) Return a single threaded pool.
static SchedulerService	threadPool(int threadCount) Requests a pool with a given size.
static SchedulerService	threadPool(int threadCount, java.lang.String threadName) Requests a pool with a given size.
static SchedulerService	threadPool(TaskPriority priority, int threadCount) Requests a pool with a given size.
static SchedulerService	threadPool(TaskPriority priority, int threadCount, java.lang.String threadName) Requests a pool with a given size.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CentralThreadlyPool

public CentralThreadlyPool()

Method Detail

increaseGenericThreads

public static void increaseGenericThreads(int count)

Increase available threads threads that can be shared across pools.

Parameters:

count - A positive number of threads to make available to the central pool

getGenericThreadCount

public static int getGenericThreadCount()

This reports the number of threads currently available for processing across all pools where the max thread count is > the guaranteed thread count.

Returns:

The number of threads currently available for general processing work

computationPool

public static SchedulerService computationPool()

Thread pool well suited for running CPU intensive computations on the tasks thread.

Returns:

Pool for CPU bound tasks

computationPool

public static SchedulerService computationPool(java.lang.String threadName)

Thread pool well suited for running CPU intensive computations on the tasks thread.

Parameters:

threadName - Name to prefix to thread while tasks on this pool execute, or null

Returns:

Pool for CPU bound tasks

lowPrioritySingleThreadPool

public static PrioritySchedulerService lowPrioritySingleThreadPool()

Low priority pool for scheduling cleanup or otherwise tasks which could be significantly delayed. This pool will only have one thread, so tasks should complete quickly or they might block other tasks.

Returns:

Single threaded pool for running or scheduling out low priority tasks

lowPrioritySingleThreadPool

public static PrioritySchedulerService lowPrioritySingleThreadPool(java.lang.String threadName)

Low priority pool for scheduling cleanup or otherwise tasks which could be significantly delayed. This pool will only have one thread, so tasks should complete quickly or they might block other tasks.

Parameters:

threadName - Name to prefix to thread while tasks on this pool execute, or null

Returns:

Single threaded pool for running or scheduling out low priority tasks

lowPriorityPool

public static SchedulerService lowPriorityPool()

Low priority pool for scheduling cleanup or otherwise tasks which could be significantly delayed. This pool will execute only on any general processing threads which are available. By default there is only one, but it can be increased by invoking increaseGenericThreads(int).

Returns:

Pool for running or scheduling out low priority tasks

lowPriorityPool

public static SchedulerService lowPriorityPool(java.lang.String threadName)

Low priority pool for scheduling cleanup or otherwise tasks which could be significantly delayed. This pool will execute only on any general processing threads which are available. By default there is only one, but it can be increased by invoking increaseGenericThreads(int).

Parameters:

threadName - Name to prefix to thread while tasks on this pool execute, or null

Returns:

Pool for running or scheduling out low priority tasks

singleThreadPool

public static PrioritySchedulerService singleThreadPool()

Return a single threaded pool. This can be useful for submitting tasks on where you don't want to worry about any concurrency or shared memory issues. If you want a single threaded pool which is forced to use the already established pool limits, consider using singleThreadPool(boolean) with false to ensure pool churn is reduced.

If returned pool will only be accepting one or two tasks, please see isolatedTaskPool() as an alternative.

Returns:

Single threaded pool for running or scheduling tasks on

singleThreadPool

public static PrioritySchedulerService singleThreadPool(java.lang.String threadName)

Return a single threaded pool. This can be useful for submitting tasks on where you don't want to worry about any concurrency or shared memory issues. If you want a single threaded pool which is forced to use the already established pool limits, consider using singleThreadPool(boolean) with false to ensure pool churn is reduced.

If returned pool will only be accepting one or two tasks, please see isolatedTaskPool(String) as an alternative.

Parameters:

threadName - Name to prefix to thread while tasks on this pool execute, or null

Returns:

Single threaded pool for running or scheduling tasks on

singleThreadPool

public static PrioritySchedulerService singleThreadPool(boolean threadGuaranteed)

Return a single threaded pool. This can be useful for submitting tasks on where you don't want to worry about any concurrency or shared memory issues.

If wanting guaranteed thread, and returned pool will only be accepting one or two tasks, please see isolatedTaskPool(String) as an alternative.

Parameters:

threadGuaranteed - true indicates that the pool manager needs to expand if necessary

Returns:

Single threaded pool for running or scheduling tasks on

singleThreadPool

public static PrioritySchedulerService singleThreadPool(boolean threadGuaranteed,
                                                        java.lang.String threadName)

Return a single threaded pool. This can be useful for submitting tasks on where you don't want to worry about any concurrency or shared memory issues.

If wanting guaranteed thread, and returned pool will only be accepting one or two tasks, please see isolatedTaskPool(String) as an alternative.

Parameters:

threadGuaranteed - true indicates that the pool manager needs to expand if necessary

threadName - Name to prefix to thread while tasks on this pool execute, or null

Returns:

Single threaded pool for running or scheduling tasks on

singleThreadPool

public static PrioritySchedulerService singleThreadPool(boolean threadGuaranteed,
                                                        java.lang.String threadName,
                                                        int threadPriority)

Return a single threaded pool. This can be useful for submitting tasks on where you don't want to worry about any concurrency or shared memory issues. This is similar to singleThreadPool(boolean, String) except that it optionally allows you to specify the priority for the thread during task execution. This priority should be inclusively between Thread.MIN_PRIORITY and Thread.MAX_PRIORITY. Typically singleThreadPool(boolean, String) will be a better option, but this may be useful in certain cases.

If wanting guaranteed thread, and returned pool will only be accepting one or two tasks, please see isolatedTaskPool(String) as an alternative.

Parameters:

threadGuaranteed - true indicates that the pool manager needs to expand if necessary

threadName - Name to prefix to thread while tasks on this pool execute, or null

threadPriority - the priority the thread should run as while executing tasks

Returns:

Single threaded pool for running or scheduling tasks on

threadPool

public static SchedulerService threadPool(int threadCount)

Requests a pool with a given size. These threads are guaranteed to be available, but general processing threads will not be available to any pools returned by this. If you want to be able to use part of the shared general processing threads use rangedThreadPool(int, int) with either a higher or negative value for maxThreads.

If returned pool will only be accepting one or two tasks, please see isolatedTaskPool() as an alternative.

Parameters:

threadCount - The number of threads that will be available to tasks submitted on the returned pool

Returns:

A pool with the requested threads available for task scheduling or execution

threadPool

public static SchedulerService threadPool(int threadCount,
                                          java.lang.String threadName)

Requests a pool with a given size. These threads are guaranteed to be available, but general processing threads will not be available to any pools returned by this. If you want to be able to use part of the shared general processing threads use rangedThreadPool(int, int) with either a higher or negative value for maxThreads.

If returned pool will only be accepting one or two tasks, please see isolatedTaskPool(String) as an alternative.

Parameters:

threadCount - The number of threads that will be available to tasks submitted on the returned pool

threadName - Name to prefix to thread while tasks on this pool execute, or null

Returns:

A pool with the requested threads available for task scheduling or execution

threadPool

public static SchedulerService threadPool(TaskPriority priority,
                                          int threadCount)

Requests a pool with a given size. These threads are guaranteed to be available, but general processing threads will not be available to any pools returned by this. If you want to be able to use part of the shared general processing threads use rangedThreadPool(TaskPriority, int, int) with either a higher or negative value for maxThreads.

If returned pool will only be accepting one or two tasks, please see isolatedTaskPool() as an alternative.

Parameters:

priority - Priority for tasks submitted on returned scheduler service

threadCount - The number of threads that will be available to tasks submitted on the returned pool

Returns:

A pool with the requested threads available for task scheduling or execution

threadPool

public static SchedulerService threadPool(TaskPriority priority,
                                          int threadCount,
                                          java.lang.String threadName)

Requests a pool with a given size. These threads are guaranteed to be available, but general processing threads will not be available to any pools returned by this. If you want to be able to use part of the shared general processing threads use rangedThreadPool(TaskPriority, int, int) with either a higher or negative value for maxThreads.

If returned pool will only be accepting one or two tasks, please see isolatedTaskPool(String) as an alternative.

Parameters:

priority - Priority for tasks submitted on returned scheduler service

threadCount - The number of threads that will be available to tasks submitted on the returned pool

threadName - Name to prefix to thread while tasks on this pool execute, or null

Returns:

A pool with the requested threads available for task scheduling or execution

rangedThreadPool

public static SchedulerService rangedThreadPool(int guaranteedThreads,
                                                int maxThreads)

Requests a pool with a given range of threads. Minimum threads are guaranteed to be available to tasks submitted to the returned threads. In addition to those minimum threads tasks submitted may run on "general processing" threads (starts at 1 but can be increased by invoking increaseGenericThreads(int)). If maxThreads is > 0 then that many shared threads in the central pool may be used, otherwise all shared threads may be able to be used.

Different ranges may have minor different performance characteristics. The most efficient returned pool would be where maxThreads == 1 (and single threaded pool). For multi-threaded pools the best option is where maxThreads is set less than or equal to guaranteedThreads + getGeneralProcessingThreadCount().

Parameters:

guaranteedThreads - Number of threads the provided pool should be guaranteed to have

maxThreads - Maximum number of threads to the returned pool can consume, or negative to use any available

Returns:

A pool with the requested specifications for task scheduling or execution

rangedThreadPool

public static SchedulerService rangedThreadPool(int guaranteedThreads,
                                                int maxThreads,
                                                java.lang.String threadName)

Requests a pool with a given range of threads. Minimum threads are guaranteed to be available to tasks submitted to the returned threads. In addition to those minimum threads tasks submitted may run on "general processing" threads (starts at 1 but can be increased by invoking increaseGenericThreads(int)). If maxThreads is > 0 then that many shared threads in the central pool may be used, otherwise all shared threads may be able to be used.

Different ranges may have minor different performance characteristics. The most efficient returned pool would be where maxThreads == 1 (and single threaded pool). For multi-threaded pools the best option is where maxThreads is set less than or equal to guaranteedThreads + getGeneralProcessingThreadCount().

Parameters:

guaranteedThreads - Number of threads the provided pool should be guaranteed to have

maxThreads - Maximum number of threads to the returned pool can consume, or negative to use any available

threadName - Name to prefix to thread while tasks on this pool execute, or null

Returns:

A pool with the requested specifications for task scheduling or execution

rangedThreadPool

public static SchedulerService rangedThreadPool(TaskPriority priority,
                                                int guaranteedThreads,
                                                int maxThreads)

Requests a pool with a given range of threads. Minimum threads are guaranteed to be available to tasks submitted to the returned threads. In addition to those minimum threads tasks submitted may run on "general processing" threads (starts at 1 but can be increased by invoking increaseGenericThreads(int)). If maxThreads is > 0 then that many shared threads in the central pool may be used, otherwise all shared threads may be able to be used.

Different ranges may have minor different performance characteristics. The most efficient returned pool would be where maxThreads == 1 (and single threaded pool). For multi-threaded pools the best option is where maxThreads is set less than or equal to guaranteedThreads + getGeneralProcessingThreadCount().

Parameters:

priority - Priority for tasks submitted on returned scheduler service

guaranteedThreads - Number of threads the provided pool should be guaranteed to have

maxThreads - Maximum number of threads to the returned pool can consume, or negative to use any available

Returns:

A pool with the requested specifications for task scheduling or execution

rangedThreadPool

public static SchedulerService rangedThreadPool(TaskPriority priority,
                                                int guaranteedThreads,
                                                int maxThreads,
                                                java.lang.String threadName)

Requests a pool with a given range of threads. Minimum threads are guaranteed to be available to tasks submitted to the returned threads. In addition to those minimum threads tasks submitted may run on "general processing" threads (starts at 1 but can be increased by invoking increaseGenericThreads(int)). If maxThreads is > 0 then that many shared threads in the central pool may be used, otherwise all shared threads may be able to be used.

Different ranges may have minor different performance characteristics. The most efficient returned pool would be where maxThreads == 1 (and single threaded pool). For multi-threaded pools the best option is where maxThreads is set less than or equal to guaranteedThreads + getGeneralProcessingThreadCount().

Parameters:

priority - Priority for tasks submitted on returned scheduler service

guaranteedThreads - Number of threads the provided pool should be guaranteed to have

maxThreads - Maximum number of threads to the returned pool can consume, or negative to use any available

threadName - Name to prefix to thread while tasks on this pool execute, or null

Returns:

A pool with the requested specifications for task scheduling or execution

isolatedTaskPool

public static SchedulerService isolatedTaskPool()

This returns a thread pool which is designed for an "isolated" task. An isolated task is one where there is not other scheduling needs in this area of code. This is equivalent to invoking singleThreadPool() for every task submitted. However that implementation is better if you have a multiple tasks you need to execute, and this one is much better if you have a single task to execute / schedule.

Implementation wise every task submitted on the returned pool will increase the pool size (if necessary) to allow execution, and then decrease the size once execution completes. Because of this, singleThreadPool() is much better if you can reuse the pool (to reduce size churn), and this is much better if you only have a single task (to reduce memory overhead).

Returns:

Pool which will ensure there is a thread available for every task executed on it

isolatedTaskPool

public static SchedulerService isolatedTaskPool(java.lang.String threadName)

This returns a thread pool which is designed for an "isolated" task. An isolated task is one where there is not other scheduling needs in this area of code. This is equivalent to invoking singleThreadPool() for every task submitted. However that implementation is better if you have a multiple tasks you need to execute, and this one is much better if you have a single task to execute / schedule.

Implementation wise every task submitted on the returned pool will increase the pool size (if necessary) to allow execution, and then decrease the size once execution completes. Because of this, singleThreadPool() is much better if you can reuse the pool (to reduce size churn), and this is much better if you only have a single task (to reduce memory overhead).

Parameters:

threadName - Name to prefix to thread while tasks on this pool execute, or null

Returns:

Pool which will ensure there is a thread available for every task executed on it