Package net.algart.arrays

Class DefaultThreadPoolFactory

java.lang.Object

net.algart.arrays.AbstractThreadPoolFactory

net.algart.arrays.DefaultThreadPoolFactory

All Implemented Interfaces:

ThreadPoolFactory

public class DefaultThreadPoolFactory
extends AbstractThreadPoolFactory
implements ThreadPoolFactory

A simple implementation of ThreadPoolFactory interface. It uses a thread pool, created by Executors.newFixedThreadPool method, and uses Arrays.SystemSettings.cpuCount() method to determine the desired number of parallel tasks, if you did not specify another number in numberOfTasks argument of the constructor or getDefaultThreadPoolFactory(int) method. See details below in comments to the methods and fields.

This class is immutable and thread-safe: there are no ways to modify settings of the created instance.

Author:

Daniel Alievsky

Constructor Summary

Constructors

Constructor	Description
DefaultThreadPoolFactory(int numberOfTasks, ThreadPoolExecutor persistentThreadPool)	Creates new instance of this class with the specified recommended number of tasks and the specified thread pool.

Method Summary

Modifier and Type	Method	Description
static DefaultThreadPoolFactory	getDefaultThreadPoolFactory()	Returns an instance of this class with the default (simplest) behaviour.
static DefaultThreadPoolFactory	getDefaultThreadPoolFactory(int numberOfTasks)	Returns an instance of this class with the specified recommended number of tasks.
ExecutorService	getThreadPool(ThreadFactory threadFactory)	This implementation returns the persistent thread pool, if it exists, or creates new thread pool by the following call: Executors.newFixedThreadPool(recommendedNumberOfTasks(), threadFactory==null ? Executors.defaultThreadFactory() : threadFactory).
ExecutorService	getThreadPool(Array sourceArray, ThreadFactory threadFactory)	This implementation returns the persistent thread pool, if it exists, or creates new thread pool by the following call: Executors.newFixedThreadPool(recommendedNumberOfTasks(sourceArray), threadFactory==null ? Executors.defaultThreadFactory() : threadFactory).
static ThreadPoolExecutor	globalThreadPool()	Returns the global thread pool, returned by getThreadPool(Array, ThreadFactory) method in factories, created by getDefaultThreadPoolFactory() and getDefaultThreadPoolFactory(int) methods.
final ExecutorService	persistentThreadPool()	Returns the persistent thread pool, returned by all calls of getThreadPool(Array, ThreadFactory) method, if it exists, or null in other case.
int	recommendedNumberOfTasks()	If this instance was created by the constructor with numberOfTasks=0 argument (or via getDefaultThreadPoolFactory() method), this implementation returns the result of Arrays.SystemSettings.cpuCount() method.
int	recommendedNumberOfTasks(Array sourceArray)	This method returns the same value as recommendedNumberOfTasks(), excepting that when the passed array is very little, this method may return less value (usually 1).
void	releaseThreadPool(ExecutorService pool)	This implementation calls pool.shutdown(), if there is no persistent thread pool (persistentThreadPool() returns null), or does nothing in other case.
ThreadPoolFactory	singleThreadVersion()	Returns new factory, identical to this one with the only exception that the recommended number of tasks in the created instance is always one.

Methods inherited from class net.algart.arrays.AbstractThreadPoolFactory

performTasks, performTasks, performTasks, performTasks, performTasks

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.algart.arrays.ThreadPoolFactory

performTasks, performTasks, performTasks, performTasks, performTasks

Constructor Details

DefaultThreadPoolFactory

public DefaultThreadPoolFactory(int numberOfTasks,
 ThreadPoolExecutor persistentThreadPool)

Creates new instance of this class with the specified recommended number of tasks and the specified thread pool.

If numberOfTasks argument is positive, it will be always returned by recommendedNumberOfTasks() and recommendedNumberOfTasks(Array) methods. If it is zero, that method will use the common algorithm, based on the system property: see comments to recommendedNumberOfTasks().

If persistentThreadPool is not null, it will be always returned by getThreadPool(Array, ThreadFactory) method and releaseThreadPool(ExecutorService) method will do nothing. In this case, please note, that if the threads, created by this pool, are not daemons, then the application will probably not be exited until you will directly call shutdown() method for the passed persistentThreadPool.

If persistentThreadPool==null, getThreadPool(Array, ThreadFactory) method will always create new thread pool and releaseThreadPool(ExecutorService) method will shutdown the passed pool.

Parameters:

numberOfTasks - the desired number of tasks.

persistentThreadPool - the desired thread pool, or null if getThreadPool(Array, ThreadFactory) should create new thread pool every time.

Throws:

IllegalArgumentException - if numberOfTasks is negative.

Method Details

globalThreadPool

public static ThreadPoolExecutor globalThreadPool()

Returns the global thread pool, returned by getThreadPool(Array, ThreadFactory) method in factories, created by getDefaultThreadPoolFactory() and getDefaultThreadPoolFactory(int) methods.

More precisely, if there is the system property "net.algart.arrays.globalThreadPoolSize", containing a positive integer value N, this method returns a global thread pool, created by Executors.newFixedThreadPool(N,...(someOurFactory)) (or analogous) operator while the first call of this method and saved in an internal static field. If this property contains an integer greater than 8192, this value is truncated to 8192. If this property contains 0 or a negative value, this method returns null (in this case, no global thread pool will be created). If there is no such property, or if it contains not a number, or if some exception occurred while calling Integer.getInteger, this method returns the default value, which is equal (in the current implementation) to Arrays.SystemSettings.availableProcessors()*MULT+1, where MULT is an integer value, stored in "net.algart.arrays.globalThreadPoolsPerCPU" system property, or default multiplier 2 if there is no such property or it contains not a number. Default value MULT=2 provides a suitable choice for most multiprocessor configurations. The value of these system properties are loaded and checked only once while initializing DefaultThreadPoolFactory class.

Note: the default value Arrays.SystemSettings.availableProcessors()*MULT+1 can be changed in future implementations. It is only guaranteed that this value is chosen not less than Arrays.SystemSettings.availableProcessors().

Note: the threads, created in the global thread pool (if it exists), are daemons. So, the application can be terminated by the usual way, even if the global thread pool contains some working threads.

Returns:

the global thread pool, usually returned by this factory, if it exists, or null in other case.

getDefaultThreadPoolFactory

public static DefaultThreadPoolFactory getDefaultThreadPoolFactory()

Returns an instance of this class with the default (simplest) behaviour. Namely, it is equivalent to getDefaultThreadPoolFactory(0). This method is the typical way for getting instances of this class.

Note: this method works very quickly (it just returns a global internal constant).

Returns:

an instance of this class with the default behaviour.

getDefaultThreadPoolFactory

public static DefaultThreadPoolFactory getDefaultThreadPoolFactory(int numberOfTasks)

Returns an instance of this class with the specified recommended number of tasks.

If numberOfTasks argument is positive, it will be always returned by recommendedNumberOfTasks() and recommendedNumberOfTasks(Array) methods. If it is zero, that method will use the common algorithm, based on the system property: see comments to recommendedNumberOfTasks().

This method is equivalent to new DefaultThreadPoolFactory(numberOfTasks, globalThreadPool()).

Note: this method works very quickly (it just returns global internal constants) in cases numberOfTasks=0 and numberOfTasks=1.

Parameters:

numberOfTasks - the desired number of tasks.

Returns:

an instance of this class with the specified recommended number of tasks.

Throws:

IllegalArgumentException - if numberOfTasks is negative.

recommendedNumberOfTasks

public int recommendedNumberOfTasks()

If this instance was created by the constructor with numberOfTasks=0 argument (or via getDefaultThreadPoolFactory() method), this implementation returns the result of Arrays.SystemSettings.cpuCount() method.

If this instance was created by the constructor with non-zero numberOfTasks argument (or via getDefaultThreadPoolFactory(int numberOfTask) method with numberOfTasks>0 method), the given numberOfTasks argument is returned always regardless of any system properties.

If this instance uses persistent thread pool, that is if persistentThreadPool()!=null (a typical situation), then the result of this method, calculated by the rules above, is also truncated by the limit Math.max(1, ((ThreadPoolExecutor)persistentThreadPool()).getCorePoolSize()) — if the previously calculated result is greater then this limit, then this limit is returned instead. So, there is a guarantee, that this method never returns a value greater than the core number of threads in a thread pool, returned by getThreadPool(ThreadFactory) and getThreadPool(Array, ThreadFactory) methods. It is important if you are going to run threads which can depend on each other.

Specified by:

recommendedNumberOfTasks in interface ThreadPoolFactory

Returns:

the recommended number of parallel tasks to perform the processing.

See Also:

• recommendedNumberOfTasks(Array)

recommendedNumberOfTasks

public int recommendedNumberOfTasks(Array sourceArray)

This method returns the same value as recommendedNumberOfTasks(), excepting that when the passed array is very little, this method may return less value (usually 1).

However, if this instance was created by the constructor with non-zero numberOfTasks argument (or via getDefaultThreadPoolFactory(int numberOfTask) method with numberOfTasks>0 method), then this method is strictly equivalent to recommendedNumberOfTasks().

Specified by:

recommendedNumberOfTasks in interface ThreadPoolFactory

Parameters:

sourceArray - some AlgART array that should be processed.

Returns:

the recommended number of parallel tasks to perform the processing.

Throws:

NullPointerException - if the argument is null.

singleThreadVersion

public ThreadPoolFactory singleThreadVersion()

Description copied from interface: ThreadPoolFactory

Returns new factory, identical to this one with the only exception that the recommended number of tasks in the created instance is always one. More precisely, the ThreadPoolFactory.recommendedNumberOfTasks() and ThreadPoolFactory.recommendedNumberOfTasks(Array) methods in the created factory always return 1, and all other methods are strictly equivalent to the corresponding methods of this instance.

Specified by:

singleThreadVersion in interface ThreadPoolFactory

Returns:

the single-thread version of this factory.

getThreadPool

public ExecutorService getThreadPool(ThreadFactory threadFactory)

This implementation returns the persistent thread pool, if it exists, or creates new thread pool by the following call: Executors.newFixedThreadPool(recommendedNumberOfTasks(), threadFactory==null ? Executors.defaultThreadFactory() : threadFactory).

Specified by:

getThreadPool in interface ThreadPoolFactory

Parameters:

threadFactory - if not null and there is no persistent thread pool, specifies the desired thread factory for using by new thread pool.

Returns:

the thread pool for parallel processing the array.

Throws:

NullPointerException - if sourceArray argument is null.

See Also:

• getThreadPool(Array, ThreadFactory)

getThreadPool

public ExecutorService getThreadPool(Array sourceArray,
 ThreadFactory threadFactory)

This implementation returns the persistent thread pool, if it exists, or creates new thread pool by the following call: Executors.newFixedThreadPool(recommendedNumberOfTasks(sourceArray), threadFactory==null ? Executors.defaultThreadFactory() : threadFactory).

Specified by:

getThreadPool in interface ThreadPoolFactory

Parameters:

sourceArray - some AlgART array that should be processed.

threadFactory - if not null and there is no persistent thread pool, specifies the desired thread factory for using by new thread pool.

Returns:

the thread pool for parallel processing the array.

Throws:

NullPointerException - if sourceArray argument is null.

releaseThreadPool

public void releaseThreadPool(ExecutorService pool)

This implementation calls pool.shutdown(), if there is no persistent thread pool (persistentThreadPool() returns null), or does nothing in other case.

Specified by:

releaseThreadPool in interface ThreadPoolFactory

Parameters:

pool - the thread pool created by the previous getThreadPool(Array, ThreadFactory) call.

Throws:

NullPointerException - if poll argument is null and there is no persistent thread pool.

persistentThreadPool

public final ExecutorService persistentThreadPool()

Returns the persistent thread pool, returned by all calls of getThreadPool(Array, ThreadFactory) method, if it exists, or null in other case. (In the second case, every call of getThreadPool(Array, ThreadFactory) method creates new thread pool.)

More precisely, if this instance was created by the constructor, this method returns its 2nd argument. If this instance was created by getDefaultThreadPoolFactory() or getDefaultThreadPoolFactory(int), this method returns the result of globalThreadPool().

Returns:

the persistent thread pool and null if it exists, or null in other case.