Simbody  3.7
SimTK::Parallel2DExecutor Class Reference

This class is used for performing multithreaded computations over two dimensional ranges. More...

+ Inheritance diagram for SimTK::Parallel2DExecutor:

Classes

class  Task
 Concrete subclasses of this abstract class represent tasks that can be executed by a Parallel2DExecutor. More...
 

Public Types

enum  RangeType {
  FullMatrix,
  HalfMatrix,
  HalfPlusDiagonal
}
 
- Public Types inherited from SimTK::PIMPLHandle< Parallel2DExecutor, Parallel2DExecutorImpl >
typedef PIMPLHandle< Parallel2DExecutor, Parallel2DExecutorImpl, false > HandleBase
 
typedef HandleBase ParentHandle
 

Public Member Functions

 Parallel2DExecutor (int gridSize, int numThreads=ParallelExecutor::getNumProcessors())
 Construct a Parallel2DExecutor. More...
 
 Parallel2DExecutor (int gridSize, ParallelExecutor &executor)
 Construct a Parallel2DExecutor. More...
 
void execute (Task &task, RangeType rangeType)
 Execute a parallel task. More...
 
ParallelExecutorgetExecutor ()
 Get the ParallelExecutor used by this object to parallelize calculations. More...
 
- Public Member Functions inherited from SimTK::PIMPLHandle< Parallel2DExecutor, Parallel2DExecutorImpl >
bool isEmptyHandle () const
 Returns true if this handle is empty, that is, does not refer to any implementation object. More...
 
bool isOwnerHandle () const
 Returns true if this handle is the owner of the implementation object to which it refers. More...
 
bool isSameHandle (const Parallel2DExecutor &other) const
 Determine whether the supplied handle is the same object as "this" PIMPLHandle. More...
 
void disown (Parallel2DExecutor &newOwner)
 Give up ownership of the implementation to an empty handle. More...
 
PIMPLHandlereferenceAssign (const Parallel2DExecutor &source)
 "Copy" assignment but with shallow (pointer) semantics. More...
 
PIMPLHandlecopyAssign (const Parallel2DExecutor &source)
 This is real copy assignment, with ordinary C++ object ("value") semantics. More...
 
void clearHandle ()
 Make this an empty handle, deleting the implementation object if this handle is the owner of it. More...
 
const Parallel2DExecutorImpl & getImpl () const
 Get a const reference to the implementation associated with this Handle. More...
 
Parallel2DExecutorImpl & updImpl ()
 Get a writable reference to the implementation associated with this Handle. More...
 
int getImplHandleCount () const
 Return the number of handles the implementation believes are referencing it. More...
 

Additional Inherited Members

- Protected Member Functions inherited from SimTK::PIMPLHandle< Parallel2DExecutor, Parallel2DExecutorImpl >
 PIMPLHandle ()
 The default constructor makes this an empty handle. More...
 
 PIMPLHandle (Parallel2DExecutorImpl *p)
 This provides consruction of a handle referencing an existing implementation object. More...
 
 PIMPLHandle (const PIMPLHandle &source)
 The copy constructor makes either a deep (value) or shallow (reference) copy of the supplied source PIMPL object, based on whether this is a "pointer semantics" (PTR=true) or "object (value) semantics" (PTR=false, default) class. More...
 
 ~PIMPLHandle ()
 Note that the destructor is non-virtual. More...
 
PIMPLHandleoperator= (const PIMPLHandle &source)
 Copy assignment makes the current handle either a deep (value) or shallow (reference) copy of the supplied source PIMPL object, based on whether this is a "pointer sematics" (PTR=true) or "object (value) semantics" (PTR=false, default) class. More...
 
void setImpl (Parallel2DExecutorImpl *p)
 Set the implementation for this empty handle. More...
 
bool hasSameImplementation (const Parallel2DExecutor &other) const
 Determine whether the supplied handle is a reference to the same implementation object as is referenced by "this" PIMPLHandle. More...
 

Detailed Description

This class is used for performing multithreaded computations over two dimensional ranges.

That is, it performs some calculation once for each pair (i, j) where i and j vary over some range. For example, it is useful for calculating pairwise forces between a set of bodies.

To use it, define a subclass of Parallel2DExecutor::Task that performs a computation. Then create a Parallel2DExecutor object and ask it to execute the task:

Parallel2DExecutor executor(gridSize);
executor.execute(myTask, Parallel2DExecutor::FullMatrix);

The Task's execute() method will be called once with each pair (i, j) where i and j vary between 0 and gridSize-1. You also can restrict it to only pairs with i > j or i >= j.

The invocations are done in parallel on multiple threads, but they are divided up in a way that avoids index conflicts between simultaneous calculations. If the task is executed with indices (i1, j1) on one thread, it is guaranteed that no other thread is simultaneously executing the task with either the first or second index equal to either i1 or j1. (More precisely, if either index of one invocation is equal to either index of another invocation, the two invocations are guaranteed to be separated by a happens-before edge.) This allows the task to modify data that is indexed by i and j without needing to worry about concurrent modifications.

The threads are created in the Parallel2DExecutor's constructor and remain active until it is deleted. This means that creating a Parallel2DExecutor is a somewhat expensive operation, but it may then be used repeatedly for executing various calculations. By default, the number of threads is chosen to be equal to the number of available processor cores. You can optionally specify a different number of threads to create. For example, using more threads than processors can sometimes lead to better processor utilitization.

Member Enumeration Documentation

◆ RangeType

Enumerator
FullMatrix 
HalfMatrix 
HalfPlusDiagonal 

Constructor & Destructor Documentation

◆ Parallel2DExecutor() [1/2]

SimTK::Parallel2DExecutor::Parallel2DExecutor ( int  gridSize,
int  numThreads = ParallelExecutor::getNumProcessors() 
)
explicit

Construct a Parallel2DExecutor.

Parameters
gridSizethe size of the range over which i and j should vary
numThreadsthe number of threads to create. By default, this is set equal to the number of processors.

◆ Parallel2DExecutor() [2/2]

SimTK::Parallel2DExecutor::Parallel2DExecutor ( int  gridSize,
ParallelExecutor executor 
)

Construct a Parallel2DExecutor.

This constructor allows you to specify an existing ParallelExecutor to use for parallelizing the calculation. This can improve efficiency by reusing an existing thread pool. It is your responsibility to make sure that the ParallelExecutor does not get deleted as long as this object exists.

Parameters
gridSizethe size of the range over which i and j should vary
executorthe ParallelExecutor to use for parallelizing calculations

Member Function Documentation

◆ execute()

void SimTK::Parallel2DExecutor::execute ( Task task,
RangeType  rangeType 
)

Execute a parallel task.

Parameters
taskthe Task to execute
rangeTypespecifies what part of the range i and j should vary over. Specify FullyMatrix to execute the task for all values of i and j between 0 and gridSize, HalfMatrix to restrict it to i > j, and HalfPlusDiagonal to restrict it to i >= j.

◆ getExecutor()

ParallelExecutor& SimTK::Parallel2DExecutor::getExecutor ( )

Get the ParallelExecutor used by this object to parallelize calculations.


The documentation for this class was generated from the following file: