Package org.threadly.concurrent.wrapper.statistics

Class ExecutorStatisticWrapper

java.lang.Object

org.threadly.concurrent.AbstractSubmitterExecutor

org.threadly.concurrent.wrapper.statistics.ExecutorStatisticWrapper

All Implemented Interfaces:

java.util.concurrent.Executor, StatisticExecutor, SubmitterExecutor

public class ExecutorStatisticWrapper
extends AbstractSubmitterExecutor
implements StatisticExecutor

Wrap an Executor to get statistics based off executions through this wrapper. If statistics are desired on the PriorityScheduler, PrioritySchedulerStatisticTracker may be a better option, taking advantages by extending and replacing logic rather than wrapping and just adding logic. Similarly SingleThreadSchedulerStatisticTracker and NoThreadSchedulerStatisticTracker should be used as an alternative for their respective schedulers.

Since:

4.6.0 (since 4.5.0 at org.threadly.concurrent.statistics)

Constructor Summary

Constructors

Constructor	Description
ExecutorStatisticWrapper(java.util.concurrent.Executor executor)	Constructs a new statistics tracker wrapper for a given executor.
ExecutorStatisticWrapper(java.util.concurrent.Executor executor, boolean accurateTime)	Constructs a new statistics tracker wrapper for a given executor.
ExecutorStatisticWrapper(java.util.concurrent.Executor executor, int maxStatisticWindowSize)	Constructs a new statistics tracker wrapper for a given executor.
ExecutorStatisticWrapper(java.util.concurrent.Executor executor, int maxStatisticWindowSize, boolean accurateTime)	Constructs a new statistics tracker wrapper for a given executor.

Method Summary

Modifier and Type	Method	Description
double	getAverageExecutionDelay()	This reports the rolling average delay from when a task was expected to run, till when the executor actually started the task.
double	getAverageExecutionDuration()	Get the average duration that tasks submitted through this executor have spent executing.
java.util.Map<java.lang.Double,java.lang.Long>	getExecutionDelayPercentiles(double... percentiles)	Gets percentile values for execution delays.
java.util.List<java.lang.Long>	getExecutionDelaySamples()	Get raw sample data for task execution delays.
java.util.Map<java.lang.Double,java.lang.Long>	getExecutionDurationPercentiles(double... percentiles)	Gets percentile values for execution duration.
java.util.List<java.lang.Long>	getExecutionDurationSamples()	Get raw sample data for task run durations.
java.util.List<Pair<java.lang.Runnable,java.lang.StackTraceElement[]>>	getLongRunningTasks(long durationLimitMillis)	Call to get a list of runnables and stack traces from tasks which have been actively executing for a longer duration than the one provided.
int	getLongRunningTasksQty(long durationLimitMillis)	Call to return the number of tasks which have been running longer than the provided duration in milliseconds.
int	getQueuedTaskCount()	Call to check how many tasks are queued waiting for execution.
long	getTotalExecutionCount()	Call to get the total quantity of tasks this executor has handled.
void	resetCollectedStats()	Clears all collected rolling statistics.

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 java.util.concurrent.Executor

execute

Methods inherited from interface org.threadly.concurrent.SubmitterExecutor

submit, submit, submit

Constructor Detail

ExecutorStatisticWrapper

public ExecutorStatisticWrapper(java.util.concurrent.Executor executor)

Constructs a new statistics tracker wrapper for a given executor. This constructor uses a sensible default for the memory usage of collected statistics.

This defaults to inaccurate time. Meaning that durations and delays may under report (but NEVER OVER what they actually were). This has the least performance impact. If you want more accurate time consider using ExecutorStatisticWrapper(Executor, boolean).

Parameters:

executor - Executor to defer executions to

ExecutorStatisticWrapper

public ExecutorStatisticWrapper(java.util.concurrent.Executor executor,
                                boolean accurateTime)

Constructs a new statistics tracker wrapper for a given executor. This constructor uses a sensible default for the memory usage of collected statistics.

Parameters:

executor - Executor to defer executions to

accurateTime - true to ensure that delays and durations are not under reported

ExecutorStatisticWrapper

public ExecutorStatisticWrapper(java.util.concurrent.Executor executor,
                                int maxStatisticWindowSize)

Constructs a new statistics tracker wrapper for a given executor.

This defaults to inaccurate time. Meaning that durations and delays may under report (but NEVER OVER what they actually were). This has the least performance impact. If you want more accurate time consider using ExecutorStatisticWrapper(Executor, int, boolean).

Parameters:

executor - Executor to defer executions to

maxStatisticWindowSize - maximum number of samples to keep internally

ExecutorStatisticWrapper

public ExecutorStatisticWrapper(java.util.concurrent.Executor executor,
                                int maxStatisticWindowSize,
                                boolean accurateTime)

Constructs a new statistics tracker wrapper for a given executor.

Parameters:

executor - Executor to defer executions to

maxStatisticWindowSize - maximum number of samples to keep internally

accurateTime - true to ensure that delays and durations are not under reported

Method Detail

getExecutionDelaySamples

public java.util.List<java.lang.Long> getExecutionDelaySamples()

Description copied from interface: StatisticExecutor

Get raw sample data for task execution delays. This raw data can be used for more advanced statistics which are not provided in this library. These can also be fed into utilities in StatisticsUtils for additional statistics.

Specified by:

getExecutionDelaySamples in interface StatisticExecutor

Returns:

A list of delay times in milliseconds before a task was executed

getAverageExecutionDelay

public double getAverageExecutionDelay()

Description copied from interface: StatisticExecutor

This reports the rolling average delay from when a task was expected to run, till when the executor actually started the task. This will return -1 if no samples have been collected yet.

Specified by:

getAverageExecutionDelay in interface StatisticExecutor

Returns:

Average delay till execution in milliseconds

getExecutionDelayPercentiles

public java.util.Map<java.lang.Double,java.lang.Long> getExecutionDelayPercentiles(double... percentiles)

Description copied from interface: StatisticExecutor

Gets percentile values for execution delays. This function accepts any decimal percentile between zero and one hundred.

The returned map's keys correspond exactly to the percentiles provided. Iterating over the returned map will iterate in order of the requested percentiles as well.

Specified by:

getExecutionDelayPercentiles in interface StatisticExecutor

Parameters:

percentiles - Percentiles requested, any decimal values between 0 and 100 (inclusive)

Returns:

Map with keys being the percentiles requested, value being the execution delay in milliseconds

getExecutionDurationSamples

public java.util.List<java.lang.Long> getExecutionDurationSamples()

Description copied from interface: StatisticExecutor

Get raw sample data for task run durations. This raw data can be used for more advanced statistics which are not provided in this library. These can also be fed into utilities in StatisticsUtils for additional statistics.

Specified by:

getExecutionDurationSamples in interface StatisticExecutor

Returns:

A list of task durations in milliseconds

getAverageExecutionDuration

public double getAverageExecutionDuration()

Description copied from interface: StatisticExecutor

Get the average duration that tasks submitted through this executor have spent executing. This only reports samples from tasks which have completed (in-progress tasks are not considered).

Specified by:

getAverageExecutionDuration in interface StatisticExecutor

Returns:

Average task execution duration in milliseconds

getExecutionDurationPercentiles

public java.util.Map<java.lang.Double,java.lang.Long> getExecutionDurationPercentiles(double... percentiles)

Description copied from interface: StatisticExecutor

Gets percentile values for execution duration. This function accepts any decimal percentile between zero and one hundred.

The returned map's keys correspond exactly to the percentiles provided. Iterating over the returned map will iterate in order of the requested percentiles as well.

Specified by:

getExecutionDurationPercentiles in interface StatisticExecutor

Parameters:

percentiles - Percentiles requested, any decimal values between 0 and 100 (inclusive)

Returns:

Map with keys being the percentiles requested, value being the execution duration in milliseconds

getLongRunningTasks

public java.util.List<Pair<java.lang.Runnable,java.lang.StackTraceElement[]>> getLongRunningTasks(long durationLimitMillis)

Description copied from interface: StatisticExecutor

Call to get a list of runnables and stack traces from tasks which have been actively executing for a longer duration than the one provided. Time in queue waiting for execution is not considered as part of the execution duration.

If only the quantity of long running tasks is needed, please use StatisticExecutor.getLongRunningTasksQty(long). Since it does not need to generate stack traces it is a cheaper alternative.

The left side of the Pair is the runnable task submitted. If the task was submitted as a Callable the Runnable will be of type: ListenableFutureTask. Casting and invoking ListenableFutureTask.getContainedCallable() will allow you to get to your original Callable.

The right side of the Pair is a single sample of what that long running tasks stack was. Because these tasks are running concurrently by the time this function returns the provided tasks may have completed.

Specified by:

getLongRunningTasks in interface StatisticExecutor

Parameters:

durationLimitMillis - Limit for tasks execution, if task execution time is below this they will be ignored

Returns:

List of long running runnables with their corresponding stack traces

getLongRunningTasksQty

public int getLongRunningTasksQty(long durationLimitMillis)

Description copied from interface: StatisticExecutor

Call to return the number of tasks which have been running longer than the provided duration in milliseconds. While iterating over running tasks, it may be possible that some previously examine tasks have completed before this ran. There is no attempt to lock tasks from starting or stopping during this check.

Specified by:

getLongRunningTasksQty in interface StatisticExecutor

Parameters:

durationLimitMillis - threshold of time in milliseconds a task must have been executing

Returns:

total quantity of tasks which have or are running longer than the provided time length

getQueuedTaskCount

public int getQueuedTaskCount()

Call to check how many tasks are queued waiting for execution. If provided an executor that allows task removal, removing tasks from that executor will cause this value to be inaccurate. A task which is submitted, and then removed (to prevent execution), will be forever seen as queued since this wrapper has no opportunity to know about such removals.

Specified by:

getQueuedTaskCount in interface StatisticExecutor

Returns:

Number of tasks still waiting to be executed.

getTotalExecutionCount

public long getTotalExecutionCount()

Description copied from interface: StatisticExecutor

Call to get the total quantity of tasks this executor has handled.

Specified by:

getTotalExecutionCount in interface StatisticExecutor

Returns:

total quantity of tasks run

resetCollectedStats

public void resetCollectedStats()

Description copied from interface: StatisticExecutor

Clears all collected rolling statistics. These are the statistics used for averages and are limited by window sizes.

This does NOT reset the total execution counts.

Specified by:

resetCollectedStats in interface StatisticExecutor