Package org.threadly.concurrent

Class 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:

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