ITK  5.4.0
Insight Toolkit
Classes | Public Types | Public Member Functions | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Private Member Functions | Private Attributes | List of all members
itk::DomainThreader< TDomainPartitioner, TAssociate > Class Template Referenceabstract

#include <itkDomainThreader.h>

Detailed Description

template<typename TDomainPartitioner, typename TAssociate>
class itk::DomainThreader< TDomainPartitioner, TAssociate >

Multi-threaded processing on a domain by processing sub-domains per thread.

This class uses a ThreadedDomainPartitioner as a helper to split the domain into subdomains. Each subdomain is then processed in the ThreadedExecution method.

The data on which to perform the processing is assumed to be members of an associating class. Therefore, to perform a threaded operation in a class, the associating class usually will declare derived versions of this class as a friend class.

To use this class, at a minimum,

If a 'threaded method' is desired to perform some data processing in a class, a derived version of this class can be defined to perform the threaded operation. Since a threaded operation is relatively complex compared to a simple serial operation, a class instead of a simple method is required. Inside this class, the method to partition the data is handled, the logic for deciding the number of work units is determined, and operations surrounding the threading are encapsulated into the class with the DetermineNumberOfWorkUnitsToUse, BeforeThreadedExecution, ThreadedExecution, and AfterThreadedExecution virtual methods.

Template Parameters
TDomainPartitionerA class that inherits from ThreadedDomainPartitioner.
TAssociateThe associated class that uses a derived version of this class as a "threaded method". The associated class usually declares derived version of this class as nested classes so there is easy access to its protected and private members in ThreadedExecution.
Examples
SphinxExamples/src/Core/Common/DoDataParallelThreading/Code.cxx.

Definition at line 66 of file itkDomainThreader.h.

+ Inheritance diagram for itk::DomainThreader< TDomainPartitioner, TAssociate >:
+ Collaboration diagram for itk::DomainThreader< TDomainPartitioner, TAssociate >:

Classes

struct  ThreadStruct
 

Public Types

using AssociateType = TAssociate
 
using ConstPointer = SmartPointer< const Self >
 
using DomainPartitionerType = TDomainPartitioner
 
using DomainType = typename DomainPartitionerType::DomainType
 
using Pointer = SmartPointer< Self >
 
using Self = DomainThreader
 
using Superclass = Object
 
- Public Types inherited from itk::Object
using ConstPointer = SmartPointer< const Self >
 
using Pointer = SmartPointer< Self >
 
using Self = Object
 
using Superclass = LightObject
 
- Public Types inherited from itk::LightObject
using ConstPointer = SmartPointer< const Self >
 
using Pointer = SmartPointer< Self >
 
using Self = LightObject
 

Public Member Functions

void Execute (AssociateType *enclosingClass, const DomainType &completeDomain)
 
MultiThreaderBaseGetMultiThreader () const
 
const char * GetNameOfClass () const override
 
virtual ThreadIdType GetNumberOfWorkUnitsUsed () const
 
virtual void SetDomainPartitioner (DomainPartitionerType *_arg)
 
virtual DomainPartitionerTypeGetModifiableDomainPartitioner ()
 
virtual void SetNumberOfWorkUnits (ThreadIdType _arg)
 
virtual ThreadIdType GetNumberOfWorkUnits () const
 
ThreadIdType GetMaximumNumberOfThreads () const
 
void SetMaximumNumberOfThreads (const ThreadIdType threads)
 
- Public Member Functions inherited from itk::Object
unsigned long AddObserver (const EventObject &event, Command *)
 
unsigned long AddObserver (const EventObject &event, Command *) const
 
unsigned long AddObserver (const EventObject &event, std::function< void(const EventObject &)> function) const
 
LightObject::Pointer CreateAnother () const override
 
virtual void DebugOff () const
 
virtual void DebugOn () const
 
CommandGetCommand (unsigned long tag)
 
bool GetDebug () const
 
MetaDataDictionaryGetMetaDataDictionary ()
 
const MetaDataDictionaryGetMetaDataDictionary () const
 
virtual ModifiedTimeType GetMTime () const
 
const char * GetNameOfClass () const override
 
virtual const TimeStampGetTimeStamp () const
 
bool HasObserver (const EventObject &event) const
 
void InvokeEvent (const EventObject &)
 
void InvokeEvent (const EventObject &) const
 
virtual void Modified () const
 
void Register () const override
 
void RemoveAllObservers ()
 
void RemoveObserver (unsigned long tag)
 
void SetDebug (bool debugFlag) const
 
void SetReferenceCount (int) override
 
void UnRegister () const noexcept override
 
void SetMetaDataDictionary (const MetaDataDictionary &rhs)
 
void SetMetaDataDictionary (MetaDataDictionary &&rrhs)
 
virtual void SetObjectName (std::string _arg)
 
virtual const std::string & GetObjectName () const
 
- Public Member Functions inherited from itk::LightObject
Pointer Clone () const
 
virtual void Delete ()
 
virtual int GetReferenceCount () const
 
void Print (std::ostream &os, Indent indent=0) const
 

Protected Member Functions

virtual void AfterThreadedExecution ()
 
virtual void BeforeThreadedExecution ()
 
virtual void DetermineNumberOfWorkUnitsUsed ()
 
 DomainThreader ()
 
virtual void SetMultiThreader (MultiThreaderBase *_arg)
 
virtual void ThreadedExecution (const DomainType &subdomain, const ThreadIdType threadId)=0
 
 ~DomainThreader () override=default
 
- Protected Member Functions inherited from itk::Object
 Object ()
 
bool PrintObservers (std::ostream &os, Indent indent) const
 
void PrintSelf (std::ostream &os, Indent indent) const override
 
virtual void SetTimeStamp (const TimeStamp &timeStamp)
 
 ~Object () override
 
- Protected Member Functions inherited from itk::LightObject
virtual LightObject::Pointer InternalClone () const
 
 LightObject ()
 
virtual void PrintHeader (std::ostream &os, Indent indent) const
 
virtual void PrintTrailer (std::ostream &os, Indent indent) const
 
virtual ~LightObject ()
 

Static Protected Member Functions

static ITK_THREAD_RETURN_FUNCTION_CALL_CONVENTION ThreaderCallback (void *arg)
 

Protected Attributes

AssociateTypem_Associate {}
 
- Protected Attributes inherited from itk::LightObject
std::atomic< int > m_ReferenceCount {}
 

Private Member Functions

void StartThreadingSequence ()
 

Private Attributes

DomainType m_CompleteDomain {}
 
DomainPartitionerType::Pointer m_DomainPartitioner {}
 
MultiThreaderBase::Pointer m_MultiThreader {}
 
ThreadIdType m_NumberOfWorkUnits {}
 
ThreadIdType m_NumberOfWorkUnitsUsed { 0 }
 

Additional Inherited Members

- Static Public Member Functions inherited from itk::Object
static bool GetGlobalWarningDisplay ()
 
static void GlobalWarningDisplayOff ()
 
static void GlobalWarningDisplayOn ()
 
static Pointer New ()
 
static void SetGlobalWarningDisplay (bool val)
 
- Static Public Member Functions inherited from itk::LightObject
static void BreakOnError ()
 
static Pointer New ()
 

Member Typedef Documentation

◆ AssociateType

template<typename TDomainPartitioner, typename TAssociate>
using itk::DomainThreader< TDomainPartitioner, TAssociate >::AssociateType = TAssociate

Definition at line 80 of file itkDomainThreader.h.

◆ ConstPointer

template<typename TDomainPartitioner, typename TAssociate>
using itk::DomainThreader< TDomainPartitioner, TAssociate >::ConstPointer = SmartPointer<const Self>

Definition at line 75 of file itkDomainThreader.h.

◆ DomainPartitionerType

template<typename TDomainPartitioner, typename TAssociate>
using itk::DomainThreader< TDomainPartitioner, TAssociate >::DomainPartitionerType = TDomainPartitioner

Definition at line 77 of file itkDomainThreader.h.

◆ DomainType

template<typename TDomainPartitioner, typename TAssociate>
using itk::DomainThreader< TDomainPartitioner, TAssociate >::DomainType = typename DomainPartitionerType::DomainType

Definition at line 78 of file itkDomainThreader.h.

◆ Pointer

template<typename TDomainPartitioner, typename TAssociate>
using itk::DomainThreader< TDomainPartitioner, TAssociate >::Pointer = SmartPointer<Self>

Definition at line 74 of file itkDomainThreader.h.

◆ Self

template<typename TDomainPartitioner, typename TAssociate>
using itk::DomainThreader< TDomainPartitioner, TAssociate >::Self = DomainThreader

Standard class type aliases.

Definition at line 72 of file itkDomainThreader.h.

◆ Superclass

template<typename TDomainPartitioner, typename TAssociate>
using itk::DomainThreader< TDomainPartitioner, TAssociate >::Superclass = Object

Definition at line 73 of file itkDomainThreader.h.

Constructor & Destructor Documentation

◆ DomainThreader()

template<typename TDomainPartitioner, typename TAssociate>
itk::DomainThreader< TDomainPartitioner, TAssociate >::DomainThreader ( )
protected

◆ ~DomainThreader()

template<typename TDomainPartitioner, typename TAssociate>
itk::DomainThreader< TDomainPartitioner, TAssociate >::~DomainThreader ( )
overrideprotecteddefault

Member Function Documentation

◆ AfterThreadedExecution()

template<typename TDomainPartitioner, typename TAssociate>
virtual void itk::DomainThreader< TDomainPartitioner, TAssociate >::AfterThreadedExecution ( )
inlineprotectedvirtual

When Execute in run, this method is run single-threaded after ThreadedExecution. Optionally collect results, etc. E.g. calculate the global minimum from the minimums calculated per thread.

Reimplemented in itk::LevelSetEvolutionComputeIterationThreader< WhitakerSparseLevelSetImage< TOutput, VDimension >, ThreadedIteratorRangePartitioner< WhitakerSparseLevelSetImage< TOutput, VDimension >::LayerConstIterator >, TLevelSetEvolution >, itk::ImageToImageMetricv4GetValueAndDerivativeThreaderBase< TDomainPartitioner, TImageToImageMetricv4 >, itk::ImageToImageMetricv4GetValueAndDerivativeThreaderBase< ThreadedImageRegionPartitioner< TImageToImageMetricv4::VirtualImageDimension >, TImageToImageMetricv4 >, itk::ImageToImageMetricv4GetValueAndDerivativeThreaderBase< ThreadedIndexedContainerPartitioner, TImageToImageMetricv4 >, itk::LevelSetEvolutionUpdateLevelSetsThreader< LevelSetDenseImage< TImage >, ThreadedImageRegionPartitioner< TImage::ImageDimension >, TLevelSetEvolution >, itk::JointHistogramMutualInformationComputeJointPDFThreaderBase< TDomainPartitioner, TJointHistogramMetric >, itk::JointHistogramMutualInformationComputeJointPDFThreaderBase< ThreadedImageRegionPartitioner< TJointHistogramMetric::VirtualImageDimension >, TJointHistogramMetric >, and itk::JointHistogramMutualInformationComputeJointPDFThreaderBase< ThreadedIndexedContainerPartitioner, TJointHistogramMetric >.

Examples
SphinxExamples/src/Core/Common/DoDataParallelThreading/Code.cxx.

Definition at line 158 of file itkDomainThreader.h.

◆ BeforeThreadedExecution()

template<typename TDomainPartitioner, typename TAssociate>
virtual void itk::DomainThreader< TDomainPartitioner, TAssociate >::BeforeThreadedExecution ( )
inlineprotectedvirtual

When Execute is run, this method is run singled-threaded before ThreadedExecution. Inside this method optional operations such as creating instance variables needed per thread may be performed.

Reimplemented in itk::LevelSetEvolutionComputeIterationThreader< WhitakerSparseLevelSetImage< TOutput, VDimension >, ThreadedIteratorRangePartitioner< WhitakerSparseLevelSetImage< TOutput, VDimension >::LayerConstIterator >, TLevelSetEvolution >, itk::ImageToImageMetricv4GetValueAndDerivativeThreaderBase< TDomainPartitioner, TImageToImageMetricv4 >, itk::ImageToImageMetricv4GetValueAndDerivativeThreaderBase< ThreadedImageRegionPartitioner< TImageToImageMetricv4::VirtualImageDimension >, TImageToImageMetricv4 >, itk::ImageToImageMetricv4GetValueAndDerivativeThreaderBase< ThreadedIndexedContainerPartitioner, TImageToImageMetricv4 >, itk::LevelSetEvolutionUpdateLevelSetsThreader< LevelSetDenseImage< TImage >, ThreadedImageRegionPartitioner< TImage::ImageDimension >, TLevelSetEvolution >, itk::JointHistogramMutualInformationComputeJointPDFThreaderBase< TDomainPartitioner, TJointHistogramMetric >, itk::JointHistogramMutualInformationComputeJointPDFThreaderBase< ThreadedImageRegionPartitioner< TJointHistogramMetric::VirtualImageDimension >, TJointHistogramMetric >, and itk::JointHistogramMutualInformationComputeJointPDFThreaderBase< ThreadedIndexedContainerPartitioner, TJointHistogramMetric >.

Examples
SphinxExamples/src/Core/Common/DoDataParallelThreading/Code.cxx.

Definition at line 140 of file itkDomainThreader.h.

◆ DetermineNumberOfWorkUnitsUsed()

template<typename TDomainPartitioner, typename TAssociate>
virtual void itk::DomainThreader< TDomainPartitioner, TAssociate >::DetermineNumberOfWorkUnitsUsed ( )
protectedvirtual

This is evaluated at the beginning of Execute() so that it can be used in BeforeThreadedExecution().

◆ Execute()

template<typename TDomainPartitioner, typename TAssociate>
void itk::DomainThreader< TDomainPartitioner, TAssociate >::Execute ( AssociateType enclosingClass,
const DomainType completeDomain 
)

Run the multi-threaded operation on the given domain.

The domain is first partitioned by the ThreadedDomainPartitioner, then the virtual methods BeforeThreadedExecution, ThreadedExecution, and AfterThreadedExecution. are run, in order.

◆ GetMaximumNumberOfThreads()

template<typename TDomainPartitioner, typename TAssociate>
ThreadIdType itk::DomainThreader< TDomainPartitioner, TAssociate >::GetMaximumNumberOfThreads ( ) const
inline

Convenience methods to set/get the maximum number of threads to use.

Warning
When setting the maximum number of threads, it will be clamped by itk::MultiThreaderBase::GetGlobalMaximumNumberOfThreads().

Definition at line 119 of file itkDomainThreader.h.

◆ GetModifiableDomainPartitioner()

template<typename TDomainPartitioner, typename TAssociate>
virtual DomainPartitionerType* itk::DomainThreader< TDomainPartitioner, TAssociate >::GetModifiableDomainPartitioner ( )
virtual

Set/Get the DomainPartitioner.

◆ GetMultiThreader()

template<typename TDomainPartitioner, typename TAssociate>
MultiThreaderBase* itk::DomainThreader< TDomainPartitioner, TAssociate >::GetMultiThreader ( ) const

Return the multithreader used by this class.

◆ GetNameOfClass()

template<typename TDomainPartitioner, typename TAssociate>
const char* itk::DomainThreader< TDomainPartitioner, TAssociate >::GetNameOfClass ( ) const
overridevirtual

◆ GetNumberOfWorkUnits()

template<typename TDomainPartitioner, typename TAssociate>
virtual ThreadIdType itk::DomainThreader< TDomainPartitioner, TAssociate >::GetNumberOfWorkUnits ( ) const
virtual

Convenience methods to set/get the desired number of work units to use.

Warning
When setting the desired number of work units, it might be clamped by itk::MultiThreaderBase::GetGlobalMaximumNumberOfThreads().

◆ GetNumberOfWorkUnitsUsed()

template<typename TDomainPartitioner, typename TAssociate>
virtual ThreadIdType itk::DomainThreader< TDomainPartitioner, TAssociate >::GetNumberOfWorkUnitsUsed ( ) const
virtual

Accessor for number of work units that were actually used in the last ThreadedExecution.

Examples
SphinxExamples/src/Core/Common/DoDataParallelThreading/Code.cxx.

◆ SetDomainPartitioner()

template<typename TDomainPartitioner, typename TAssociate>
virtual void itk::DomainThreader< TDomainPartitioner, TAssociate >::SetDomainPartitioner ( DomainPartitionerType _arg)
virtual

Set/Get the DomainPartitioner.

◆ SetMaximumNumberOfThreads()

template<typename TDomainPartitioner, typename TAssociate>
void itk::DomainThreader< TDomainPartitioner, TAssociate >::SetMaximumNumberOfThreads ( const ThreadIdType  threads)

Convenience methods to set/get the maximum number of threads to use.

Warning
When setting the maximum number of threads, it will be clamped by itk::MultiThreaderBase::GetGlobalMaximumNumberOfThreads().

◆ SetMultiThreader()

template<typename TDomainPartitioner, typename TAssociate>
virtual void itk::DomainThreader< TDomainPartitioner, TAssociate >::SetMultiThreader ( MultiThreaderBase _arg)
protectedvirtual

◆ SetNumberOfWorkUnits()

template<typename TDomainPartitioner, typename TAssociate>
virtual void itk::DomainThreader< TDomainPartitioner, TAssociate >::SetNumberOfWorkUnits ( ThreadIdType  _arg)
virtual

Convenience methods to set/get the desired number of work units to use.

Warning
When setting the desired number of work units, it might be clamped by itk::MultiThreaderBase::GetGlobalMaximumNumberOfThreads().

◆ StartThreadingSequence()

template<typename TDomainPartitioner, typename TAssociate>
void itk::DomainThreader< TDomainPartitioner, TAssociate >::StartThreadingSequence ( )
private

◆ ThreadedExecution()

template<typename TDomainPartitioner, typename TAssociate>
virtual void itk::DomainThreader< TDomainPartitioner, TAssociate >::ThreadedExecution ( const DomainType subdomain,
const ThreadIdType  threadId 
)
protectedpure virtual

Do the threaded operation, somewhat like ThreadedGenerateData in an ImageSource.

Parameters
subdomainThe subdomain to operate on.
threadIdThe identifier for the current thread. Data to perform the operation on can be accessed by dereferencing this->m_Associate, which has direct access to private and protected members the enclosing class.

Implemented in itk::GradientDescentOptimizerBasev4ModifyGradientByLearningRateThreaderTemplate< TInternalComputationValueType >, itk::GradientDescentOptimizerBasev4ModifyGradientByScalesThreaderTemplate< TInternalComputationValueType >, itk::QuasiNewtonOptimizerv4EstimateNewtonStepThreaderTemplate< TInternalComputationValueType >, itk::LevelSetEvolutionComputeIterationThreader< WhitakerSparseLevelSetImage< TOutput, VDimension >, ThreadedIteratorRangePartitioner< WhitakerSparseLevelSetImage< TOutput, VDimension >::LayerConstIterator >, TLevelSetEvolution >, itk::ImageToImageMetricv4GetValueAndDerivativeThreader< ThreadedIndexedContainerPartitioner, TImageToImageMetricv4 >, itk::JointHistogramMutualInformationComputeJointPDFThreader< ThreadedIndexedContainerPartitioner, TJointHistogramMetric >, itk::ImageToImageMetricv4GetValueAndDerivativeThreader< ThreadedImageRegionPartitioner< TImageToImageMetricv4::VirtualImageDimension >, TImageToImageMetricv4 >, itk::LevelSetEvolutionComputeIterationThreader< LevelSetDenseImage< TImage >, ThreadedImageRegionPartitioner< TImage::ImageDimension >, TLevelSetEvolution >, itk::JointHistogramMutualInformationComputeJointPDFThreader< ThreadedImageRegionPartitioner< TJointHistogramMetric::VirtualImageDimension >, TJointHistogramMetric >, itk::LevelSetEvolutionUpdateLevelSetsThreader< LevelSetDenseImage< TImage >, ThreadedImageRegionPartitioner< TImage::ImageDimension >, TLevelSetEvolution >, and itk::LevelSetEvolutionComputeIterationThreader< LevelSetDenseImage< TImage >, ThreadedIteratorRangePartitioner< TLevelSetEvolution::DomainMapImageFilterType::DomainMapType::const_iterator >, TLevelSetEvolution >.

Examples
SphinxExamples/src/Core/Common/DoDataParallelThreading/Code.cxx.

◆ ThreaderCallback()

template<typename TDomainPartitioner, typename TAssociate>
static ITK_THREAD_RETURN_FUNCTION_CALL_CONVENTION itk::DomainThreader< TDomainPartitioner, TAssociate >::ThreaderCallback ( void *  arg)
staticprotected

Static function used as a "callback" by the MultiThreaderBase. The threading library will call this routine for each thread, which will delegate the control to the ThreadFunctor.

Member Data Documentation

◆ m_Associate

template<typename TDomainPartitioner, typename TAssociate>
AssociateType* itk::DomainThreader< TDomainPartitioner, TAssociate >::m_Associate {}
protected

Definition at line 169 of file itkDomainThreader.h.

◆ m_CompleteDomain

template<typename TDomainPartitioner, typename TAssociate>
DomainType itk::DomainThreader< TDomainPartitioner, TAssociate >::m_CompleteDomain {}
private

Definition at line 188 of file itkDomainThreader.h.

◆ m_DomainPartitioner

template<typename TDomainPartitioner, typename TAssociate>
DomainPartitionerType::Pointer itk::DomainThreader< TDomainPartitioner, TAssociate >::m_DomainPartitioner {}
private

Definition at line 187 of file itkDomainThreader.h.

◆ m_MultiThreader

template<typename TDomainPartitioner, typename TAssociate>
MultiThreaderBase::Pointer itk::DomainThreader< TDomainPartitioner, TAssociate >::m_MultiThreader {}
private

Definition at line 189 of file itkDomainThreader.h.

◆ m_NumberOfWorkUnits

template<typename TDomainPartitioner, typename TAssociate>
ThreadIdType itk::DomainThreader< TDomainPartitioner, TAssociate >::m_NumberOfWorkUnits {}
private

Definition at line 186 of file itkDomainThreader.h.

◆ m_NumberOfWorkUnitsUsed

template<typename TDomainPartitioner, typename TAssociate>
ThreadIdType itk::DomainThreader< TDomainPartitioner, TAssociate >::m_NumberOfWorkUnitsUsed { 0 }
private

Store the actual number of work units used, which may be less than the number allocated by the threader if the object does not split well into that number. This value is determined at the beginning of Execute().

Definition at line 185 of file itkDomainThreader.h.


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