agi.foundation.infrastructure.threading

(agi.foundation.core-2024r3.jar)

Class ThreadedCalculation

java.lang.Object

agi.foundation.infrastructure.threading.ThreadedCalculation

All Implemented Interfaces:

IDisposable, AutoCloseable

public abstract class ThreadedCalculation
extends Object
implements IDisposable

Parallelizes calculations across multiple threads. Most calculations can be parallelized using the static methods on this class. Or, in more advanced scenarios, derive from this class to implement a multithreaded calculation. Calculations are multithreaded according to the ThreadingPolicy.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ThreadedCalculation.BodyCallback<TParameter> A delegate representing the body of a multithreaded 'for' loop.
static class	ThreadedCalculation.BodyCallback2<TParameter1,TParameter2> A delegate representing the body of a multithreaded 'for' loop.
static class	ThreadedCalculation.BodyCallbackWithProgress<TParameter> A delegate representing the body of a multithreaded 'for' loop, where each iteration of the loop intends to provide detailed information about its progress.
static class	ThreadedCalculation.BodyCallbackWithProgress2<TParameter1,TParameter2> A delegate representing the body of a multithreaded 'for' loop, where each iteration of the loop intends to provide detailed information about its progress.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ThreadedCalculation() Initializes a new instance.

Method Summary

Modifier and Type	Method and Description
static <TParameter1,TParameter2> void	_for(int start, int stop, TParameter1 parameter1, TParameter2 parameter2, ITrackCalculationProgress tracker, ThreadedCalculation.BodyCallback2<TParameter1,TParameter2> body) A 'for' loop that is parallelized among multiple threads according to the ThreadingPolicy active in the calling thread.
static <TParameter1,TParameter2> void	_for(int start, int stop, TParameter1 parameter1, TParameter2 parameter2, ITrackCalculationProgress tracker, ThreadedCalculation.BodyCallbackWithProgress2<TParameter1,TParameter2> body) A 'for' loop that is parallelized among multiple threads according to the ThreadingPolicy active in the calling thread.
static <TParameter> void	_for(int start, int stop, TParameter parameter, ITrackCalculationProgress tracker, ThreadedCalculation.BodyCallback<TParameter> body) A 'for' loop that is parallelized among multiple threads according to the ThreadingPolicy active in the calling thread.
static <TParameter> void	_for(int start, int stop, TParameter parameter, ITrackCalculationProgress tracker, ThreadedCalculation.BodyCallbackWithProgress<TParameter> body) A 'for' loop that is parallelized among multiple threads according to the ThreadingPolicy active in the calling thread.
void	dispose() Releases any resources associated with this instance.
protected void	dispose(boolean disposing) Releases any resources associated with this instance.
void	executeInOneThread() Starts the calculation using the calling thread as the one and only worker thread.
protected abstract void	executeWorker(int threadNumber) Implement this method to perform the calculation.
protected void	finish() This method is called after all worker threads have finished executing.
boolean	getContinueExecution() Gets a value indicating whether a thread should continue its threaded execution.
boolean	getMultithreadSubCalculations() Gets a value indicating whether subcalculations should use the current ThreadingPolicy.
int	getNumberOfThreads() Gets the number of threads to be used to perform the calculation.
void	setContinueExecution(boolean value) Sets a value indicating whether a thread should continue its threaded execution.
void	setMultithreadSubCalculations(boolean value) Sets a value indicating whether subcalculations should use the current ThreadingPolicy.
void	start() Starts the threaded calculation.
void	waitUntilDone() Blocks the calling thread until the calculation has completed.

Methods inherited from class java.lang.Object

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

Methods inherited from interface agi.foundation.compatibility.IDisposable

close

Constructor Detail

ThreadedCalculation

protected ThreadedCalculation()

Initializes a new instance.

Method Detail

_for

public static <TParameter> void _for(int start,
                                     int stop,
                                     TParameter parameter,
                                     @Nullable
                                     ITrackCalculationProgress tracker,
                                     @Nonnull
                                     ThreadedCalculation.BodyCallback<TParameter> body)

A 'for' loop that is parallelized among multiple threads according to the ThreadingPolicy active in the calling thread. The loop behaves as if written as for (int i = start; i < stop; ++i). Inside the body callback, the ThreadingPolicy will be configured to use only the calling thread for any further parallelizable operations. This usually improves performance by putting the parallelism where it is most useful: in the 'for' loop itself. However, if you do wish to parallelize operations invoked inside the 'for' loop, you must explicitly set the ThreadingPolicy inside the callback.

Type Parameters:

TParameter - The type of an instance that is passed to the body of the loop.

Parameters:

start - The start of the loop.

stop - The end of the loop. The body is NOT executed for this value.

parameter - A parameter that is passed to the body of the loop. If this instance implements IThreadAware and IsThreadSafe (get) returns false, a copy of the parameter is made for each thread using CopyForAnotherThread.

tracker - The object to which progress is reported and that is able to cancel this operation before it is complete, or null.

body - The body of the loop.

_for

public static <TParameter1,TParameter2> void _for(int start,
                                                  int stop,
                                                  TParameter1 parameter1,
                                                  TParameter2 parameter2,
                                                  @Nullable
                                                  ITrackCalculationProgress tracker,
                                                  @Nonnull
                                                  ThreadedCalculation.BodyCallback2<TParameter1,TParameter2> body)

A 'for' loop that is parallelized among multiple threads according to the ThreadingPolicy active in the calling thread. The loop behaves as if written as for (int i = start; i < stop; ++i). Inside the body callback, the ThreadingPolicy will be configured to use only the calling thread for any further parallelizable operations. This usually improves performance by putting the parallelism where it is most useful: in the 'for' loop itself. However, if you do wish to parallelize operations invoked inside the 'for' loop, you must explicitly set the ThreadingPolicy inside the callback.

Type Parameters:

TParameter1 - The type of the first parameter that is passed to the body of the loop.

TParameter2 - The type of the second parameter that is passed to the body of the loop.

Parameters:

start - The start of the loop.

stop - The end of the loop. The body is NOT executed for this value.

parameter1 - The first parameter that is passed to the body of the loop. If this instance implements IThreadAware and IsThreadSafe (get) returns false, a copy of the parameter is made for each thread using CopyForAnotherThread.

parameter2 - The second parameter that is passed to the body of the loop. If this instance implements IThreadAware and IsThreadSafe (get) returns false, a copy of the parameter is made for each thread using CopyForAnotherThread.

tracker - The object to which progress is reported and that is able to cancel this operation before it is complete, or null.

body - The body of the loop.

_for

public static <TParameter> void _for(int start,
                                     int stop,
                                     TParameter parameter,
                                     @Nullable
                                     ITrackCalculationProgress tracker,
                                     @Nonnull
                                     ThreadedCalculation.BodyCallbackWithProgress<TParameter> body)

A 'for' loop that is parallelized among multiple threads according to the ThreadingPolicy active in the calling thread. The loop behaves as if written as for (int i = start; i < stop; ++i). Inside the body callback, the ThreadingPolicy will be configured to use only the calling thread for any further parallelizable operations. This usually improves performance by putting the parallelism where it is most useful: in the 'for' loop itself. However, if you do wish to parallelize operations invoked inside the 'for' loop, you must explicitly set the ThreadingPolicy inside the callback.

The body of the 'for' loop is given an ITrackCalculationProgress instance that can be used to report detailed information about the progress of individual loop iterations. It is not recommended to use this overload when looping through a large number of iterations or when detailed information about the progress of individual iterations is not required, because there is some overhead to the detailed progress reporting.

Type Parameters:

TParameter - The type of an instance that is passed to the body of the loop.

Parameters:

start - The start of the loop.

stop - The end of the loop. The body is NOT executed for this value.

parameter - A parameter that is passed to the body of the loop. If this instance implements IThreadAware and IsThreadSafe (get) returns false, a copy of the parameter is made for each thread using CopyForAnotherThread.

tracker - The object to which progress is reported and that is able to cancel this operation before it is complete, or null.

body - The body of the loop.

_for

public static <TParameter1,TParameter2> void _for(int start,
                                                  int stop,
                                                  TParameter1 parameter1,
                                                  TParameter2 parameter2,
                                                  @Nullable
                                                  ITrackCalculationProgress tracker,
                                                  @Nonnull
                                                  ThreadedCalculation.BodyCallbackWithProgress2<TParameter1,TParameter2> body)

A 'for' loop that is parallelized among multiple threads according to the ThreadingPolicy active in the calling thread. The loop behaves as if written as for (int i = start; i < stop; ++i). Inside the body callback, the ThreadingPolicy will be configured to use only the calling thread for any further parallelizable operations. This usually improves performance by putting the parallelism where it is most useful: in the 'for' loop itself. However, if you do wish to parallelize operations invoked inside the 'for' loop, you must explicitly set the ThreadingPolicy inside the callback.

The body of the 'for' loop is given an ITrackCalculationProgress instance that can be used to report detailed information about the progress of individual loop iterations. It is not recommended to use this overload when looping through a large number of iterations or when detailed information about the progress of individual iterations is not required, because there is some overhead to the detailed progress reporting.

Type Parameters:

TParameter1 - The type of the first parameter that is passed to the body of the loop.

TParameter2 - The type of the second parameter that is passed to the body of the loop.

Parameters:

start - The start of the loop.

stop - The end of the loop. The body is NOT executed for this value.

parameter1 - The first parameter that is passed to the body of the loop. If this instance implements IThreadAware and IsThreadSafe (get) returns false, a copy of the parameter is made for each thread using CopyForAnotherThread.

parameter2 - The second parameter that is passed to the body of the loop. If this instance implements IThreadAware and IsThreadSafe (get) returns false, a copy of the parameter is made for each thread using CopyForAnotherThread.

tracker - The object to which progress is reported and that is able to cancel this operation before it is complete, or null.

body - The body of the loop.

getNumberOfThreads

public final int getNumberOfThreads()

Gets the number of threads to be used to perform the calculation.

The number of threads to use is obtained from the current ThreadingPolicy when an instance of this class is constructed and is constant thereafter.

getContinueExecution

public final boolean getContinueExecution()

Gets a value indicating whether a thread should continue its threaded execution. It is the responsibility of derived classes to check this value in their ThreadedCalculation.executeWorker(int) method and to stop their execution if it is false.

setContinueExecution

public final void setContinueExecution(boolean value)

Sets a value indicating whether a thread should continue its threaded execution. It is the responsibility of derived classes to check this value in their ThreadedCalculation.executeWorker(int) method and to stop their execution if it is false.

getMultithreadSubCalculations

public final boolean getMultithreadSubCalculations()

Gets a value indicating whether subcalculations should use the current ThreadingPolicy. By default, this is false, indicating that the subcalculations will see a ThreadingPolicy specifying that further operations be executed in the thread that invoked those operations. New threads created for use by the threaded calculation will use the default threading policy that was previously configured by calling ThreadingPolicy.useCurrentAsDefault().

setMultithreadSubCalculations

public final void setMultithreadSubCalculations(boolean value)

Sets a value indicating whether subcalculations should use the current ThreadingPolicy. By default, this is false, indicating that the subcalculations will see a ThreadingPolicy specifying that further operations be executed in the thread that invoked those operations. New threads created for use by the threaded calculation will use the default threading policy that was previously configured by calling ThreadingPolicy.useCurrentAsDefault().

start

public final void start()

Starts the threaded calculation. This method returns immediately after creating the appropriate number of threads. It does not wait for the calculation to be completed.

executeInOneThread

public final void executeInOneThread()

Starts the calculation using the calling thread as the one and only worker thread. This method does not return until the calculation is completed.

finish

protected void finish()

This method is called after all worker threads have finished executing. It Does nothing if not overridden by the derived class.

waitUntilDone

public final void waitUntilDone()

Blocks the calling thread until the calculation has completed. If an exception occurs (or has already occurred) in any of the calculation threads, this method will throw a ThreadException wrapping the exception that was thrown by the calculation thread. The actual exception that occurred can be found in the InnerException (get) property.

executeWorker

protected abstract void executeWorker(int threadNumber)

Implement this method to perform the calculation. It is called NumberOfThreads (get) times, each call in a separate thread.

Parameters:

threadNumber - The number of the thread, starting at 0 and increasing to NumberOfThreads (get) - 1.

dispose

public final void dispose()

Releases any resources associated with this instance.

Specified by:

dispose in interface IDisposable

dispose

protected void dispose(boolean disposing)

Releases any resources associated with this instance.

Parameters:

disposing - true to release both managed and unmanaged resources; false to release only unmanaged resources.