org.threadly.concurrent

Class UnfairExecutor

java.lang.Object

org.threadly.concurrent.AbstractSubmitterExecutor

org.threadly.concurrent.UnfairExecutor

All Implemented Interfaces:

java.util.concurrent.Executor, SubmitterExecutor

public class UnfairExecutor
extends AbstractSubmitterExecutor

A very high performance SubmitterExecutor implementation. Though to get those performance gains, some guarantees are reduced. Most prominently is execution order, this scheduler does not ensure that tasks are executed in the order they are submitted, but rather tasks are consumed however is fastest.

This executor has an execution queue per thread. That way each thread has a many producer, one consumer safety guarantees. Compared to other pools which have to deal with a many to many thread safety issue. Determining the thread queue may be based on a variety of information. A couple built in distribution solutions are UnfairExecutor.TaskHashXorTimeStripeGenerator (default) and UnfairExecutor.AtomicStripeGenerator.

This scheduler will work best when the following conditions are true. First because a long running task can block other tasks from running (even when other threads are idle). It is best that tasks should be equally sized. We also recommend having thread counts which are prime numbers for a more even hash distribution. It is also important to recognize that it is generally a bad idea to block any of these threads waiting for results from processing that is expected to happen on the same executor.

Since:

4.5.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	UnfairExecutor.AtomicStripeGenerator Stripe generator which will round robin distribute tasks to threads.
static class	UnfairExecutor.TaskHashXorTimeStripeGenerator Generator which will determine the task stripe by using the identity hash of the runnable and Clock.lastKnownTimeNanos().
static interface	UnfairExecutor.TaskStripeGenerator Strategy for taking in a task and producing a long which will be translated to which thread the task should be distributed on to.

Constructor Summary

Constructors

Constructor and Description
UnfairExecutor(int threadCount) Constructs a new UnfairExecutor with a provided thread count.
UnfairExecutor(int threadCount, boolean useDaemonThreads) Constructs a new UnfairExecutor with a provided thread count.
UnfairExecutor(int threadCount, boolean useDaemonThreads, UnfairExecutor.TaskStripeGenerator stripeGenerator) Constructs a new UnfairExecutor with a provided thread count.
UnfairExecutor(int threadCount, java.util.concurrent.ThreadFactory threadFactory) Constructs a new UnfairExecutor with a provided thread count and factory.
UnfairExecutor(int threadCount, java.util.concurrent.ThreadFactory threadFactory, UnfairExecutor.TaskStripeGenerator stripeGenerator) Constructs a new UnfairExecutor with a provided thread count and factory.
UnfairExecutor(int threadCount, UnfairExecutor.TaskStripeGenerator stripeGenerator) Constructs a new UnfairExecutor with a provided thread count.

Method Summary

Modifier and Type	Method and Description
void	awaitTermination() Block until the thread pool has shutdown and all threads have been stopped.
boolean	awaitTermination(long timeoutMillis) Block until the thread pool has shutdown and all threads have been stopped.
boolean	isShutdown() Function to check if the thread pool is currently accepting and handling tasks.
void	shutdown() Stops any new tasks from being submitted to the pool.
java.util.List<java.lang.Runnable>	shutdownNow() Stops any new tasks from being submitted to the pool.

Methods inherited from class org.threadly.concurrent.AbstractSubmitterExecutor

execute, submit, submit

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.threadly.concurrent.SubmitterExecutor

submit

Constructor Detail

UnfairExecutor

public UnfairExecutor(int threadCount)

Constructs a new UnfairExecutor with a provided thread count. This defaults to using daemon threads. This also defaults to using the UnfairExecutor.TaskHashXorTimeStripeGenerator.

Parameters:

threadCount - Number of threads, recommended to be a prime number

UnfairExecutor

public UnfairExecutor(int threadCount,
                      UnfairExecutor.TaskStripeGenerator stripeGenerator)

Constructs a new UnfairExecutor with a provided thread count. This defaults to using daemon threads.

Possible built in stripe generators for use would be UnfairExecutor.AtomicStripeGenerator or UnfairExecutor.TaskHashXorTimeStripeGenerator.

Parameters:

threadCount - Number of threads, recommended to be a prime number

stripeGenerator - Generator for figuring out how a task is assigned to a thread

UnfairExecutor

public UnfairExecutor(int threadCount,
                      boolean useDaemonThreads)

Constructs a new UnfairExecutor with a provided thread count. This also defaults to using the UnfairExecutor.TaskHashXorTimeStripeGenerator.

Parameters:

threadCount - Number of threads, recommended to be a prime number

useDaemonThreads - true if created threads should be daemon

UnfairExecutor

public UnfairExecutor(int threadCount,
                      boolean useDaemonThreads,
                      UnfairExecutor.TaskStripeGenerator stripeGenerator)

Constructs a new UnfairExecutor with a provided thread count.

Possible built in stripe generators for use would be UnfairExecutor.AtomicStripeGenerator or UnfairExecutor.TaskHashXorTimeStripeGenerator.

Parameters:

threadCount - Number of threads, recommended to be a prime number

useDaemonThreads - true if created threads should be daemon

stripeGenerator - Generator for figuring out how a task is assigned to a thread

UnfairExecutor

public UnfairExecutor(int threadCount,
                      java.util.concurrent.ThreadFactory threadFactory)

Constructs a new UnfairExecutor with a provided thread count and factory. This also defaults to using the UnfairExecutor.TaskHashXorTimeStripeGenerator.

Parameters:

threadCount - Number of threads, recommended to be a prime number

threadFactory - thread factory for producing new threads within executor

UnfairExecutor

public UnfairExecutor(int threadCount,
                      java.util.concurrent.ThreadFactory threadFactory,
                      UnfairExecutor.TaskStripeGenerator stripeGenerator)

Constructs a new UnfairExecutor with a provided thread count and factory.

Possible built in stripe generators for use would be UnfairExecutor.AtomicStripeGenerator or UnfairExecutor.TaskHashXorTimeStripeGenerator.

Parameters:

threadCount - Number of threads, recommended to be a prime number

threadFactory - thread factory for producing new threads within executor

stripeGenerator - Generator for figuring out how a task is assigned to a thread

Method Detail

isShutdown

public boolean isShutdown()

Function to check if the thread pool is currently accepting and handling tasks.

Returns:

true if thread pool is running

shutdown

public void shutdown()

Stops any new tasks from being submitted to the pool. But allows all tasks which are submitted to execute, or scheduled (and have elapsed their delay time) to run. If recurring tasks are present they will also be unable to reschedule. This call will not block to wait for the shutdown of the scheduler to finish. If shutdown() or shutdownNow() has already been called, this will have no effect.

If you wish to not want to run any queued tasks you should use shutdownNow().

shutdownNow

public java.util.List<java.lang.Runnable> shutdownNow()

Stops any new tasks from being submitted to the pool. If any tasks are waiting for execution they will be prevented from being run. If a task is currently running it will be allowed to finish (though this call will not block waiting for it to finish).

Returns:

returns a list of runnables which were waiting in the queue to be run at time of shutdown

awaitTermination

public void awaitTermination()
                      throws java.lang.InterruptedException

Block until the thread pool has shutdown and all threads have been stopped. If neither shutdown() or shutdownNow() is invoked, then this will block forever.

Throws:

java.lang.InterruptedException - Thrown if blocking thread is interrupted waiting for shutdown

awaitTermination

public boolean awaitTermination(long timeoutMillis)
                         throws java.lang.InterruptedException

Block until the thread pool has shutdown and all threads have been stopped. If neither shutdown() or shutdownNow() is invoked, then this will block until the timeout is reached.

Parameters:

timeoutMillis - time to block and wait for thread pool to shutdown

Returns:

true if the pool has shutdown, false if timeout was reached

Throws:

java.lang.InterruptedException - Thrown if blocking thread is interrupted waiting for shutdown