#include <itkMultiThreaderBase.h>

Inheritance diagram for itk::MultiThreaderBase:

Collaboration diagram for itk::MultiThreaderBase:

Detailed Description

A class for performing multithreaded execution.

Multithreaders are a class hierarchy that provides support for multithreaded execution by abstracting away platform-specific details. This class can be used to execute a single method on multiple threads or to parallelize an operation over a given image region or array.

Definition at line 61 of file itkMultiThreaderBase.h.

Classes
struct	ArrayCallback

struct	RegionAndCallback

struct	WorkUnitInfo

Public Types
using	ArrayThreadingFunctorType = std::function< void(SizeValueType) >

using	ConstPointer = SmartPointer< const Self >

using	Pointer = SmartPointer< Self >

using	Self = MultiThreaderBase

using	Superclass = Object

template<unsigned int VDimension>
using	TemplatedThreadingFunctorType = std::function< void(const ImageRegion< VDimension > &)>

enum	ThreaderType { Platform = 0, First = Platform, Pool, TBB, Last = TBB, Unknown = -1 }

using	ThreadingFunctorType = std::function< void(const IndexValueType index[], const SizeValueType size[])>

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
virtual const char *	GetNameOfClass () const

virtual void	ParallelizeArray (SizeValueType firstIndex, SizeValueType lastIndexPlus1, ArrayThreadingFunctorType aFunc, ProcessObject *filter)

virtual void	SetSingleMethod (ThreadFunctionType, void *data)=0

virtual void	SingleMethodExecute ()=0


virtual void	SetMaximumNumberOfThreads (ThreadIdType numberOfThreads)

virtual ThreadIdType	GetMaximumNumberOfThreads () const


virtual void	SetNumberOfWorkUnits (ThreadIdType numberOfWorkUnits)

virtual ThreadIdType	GetNumberOfWorkUnits () const


	itkLegacyMacro (static void SetGlobalDefaultUseThreadPool(const bool GlobalDefaultUseThreadPool))

	itkLegacyMacro (static bool GetGlobalDefaultUseThreadPool())


template<unsigned int VDimension>
ITK_TEMPLATE_EXPORT void	ParallelizeImageRegion (const ImageRegion< VDimension > &requestedRegion, TemplatedThreadingFunctorType< VDimension > funcP, ProcessObject *filter)

Public Member Functions inherited from itk::Object
unsigned long	AddObserver (const EventObject &event, Command *)

unsigned long	AddObserver (const EventObject &event, Command *) const

LightObject::Pointer	CreateAnother () const override

virtual void	DebugOff () const

virtual void	DebugOn () const

Command *	GetCommand (unsigned long tag)

bool	GetDebug () const

MetaDataDictionary &	GetMetaDataDictionary ()

const MetaDataDictionary &	GetMetaDataDictionary () const

virtual ModifiedTimeType	GetMTime () const

virtual const TimeStamp &	GetTimeStamp () 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 noexceptoverride

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
virtual void	Delete ()

virtual int	GetReferenceCount () const

	itkCloneMacro (Self)

void	Print (std::ostream &os, Indent indent=0) const

Static Public Member Functions
static Pointer	New ()

static ThreaderType	ThreaderTypeFromString (std::string threaderString)


static void	SetGlobalMaximumNumberOfThreads (ThreadIdType val)

static ThreadIdType	GetGlobalMaximumNumberOfThreads ()


static std::string	ThreaderTypeToString (ThreaderType threader)


static void	SetGlobalDefaultThreader (ThreaderType threaderType)

static ThreaderType	GetGlobalDefaultThreader ()


static void	SetGlobalDefaultNumberOfThreads (ThreadIdType val)

static ThreadIdType	GetGlobalDefaultNumberOfThreads ()

Static Public Member Functions inherited from itk::Object
static bool	GetGlobalWarningDisplay ()

static void	GlobalWarningDisplayOff ()

static void	GlobalWarningDisplayOn ()

static Pointer	New ()

static void	SetGlobalWarningDisplay (bool flag)

Static Public Member Functions inherited from itk::LightObject
static void	BreakOnError ()

static Pointer	New ()

ThreadIdType	m_NumberOfWorkUnits

ThreadIdType	m_MaximumNumberOfThreads

ThreadFunctionType	m_SingleMethod

void *	m_SingleData

static MultiThreaderBaseGlobals *	m_PimplGlobals

class	ProcessObject

static void	HandleFilterProgress (ProcessObject *filter, float progress=-1.0f)

template<unsigned int VDimension>
ITK_TEMPLATE_EXPORT void	ParallelizeImageRegionRestrictDirection (unsigned int restrictedDirection, const ImageRegion< VDimension > &requestedRegion, TemplatedThreadingFunctorType< VDimension > funcP, ProcessObject *filter)

virtual void	ParallelizeImageRegion (unsigned int dimension, const IndexValueType index[], const SizeValueType size[], ThreadingFunctorType funcP, ProcessObject *filter)

	MultiThreaderBase ()

	~MultiThreaderBase () override

void	PrintSelf (std::ostream &os, Indent indent) const override

static ITK_THREAD_RETURN_FUNCTION_CALL_CONVENTION	ParallelizeArrayHelper (void *arg)

static ITK_THREAD_RETURN_FUNCTION_CALL_CONVENTION	ParallelizeImageRegionHelper (void *arg)

static ITK_THREAD_RETURN_FUNCTION_CALL_CONVENTION	SingleMethodProxy (void *arg)

	itkGetGlobalDeclarationMacro (MultiThreaderBaseGlobals, PimplGlobals)

static ThreadIdType	GetGlobalDefaultNumberOfThreadsByPlatform ()

Additional Inherited Members
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 &time)

	~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 ()

Protected Attributes inherited from itk::LightObject
std::atomic< int >	m_ReferenceCount

Member Typedef Documentation

using itk::MultiThreaderBase::ArrayThreadingFunctorType = std::function< void( SizeValueType ) >

Definition at line 249 of file itkMultiThreaderBase.h.

using itk::MultiThreaderBase::ConstPointer = SmartPointer<const Self>

Definition at line 70 of file itkMultiThreaderBase.h.

using itk::MultiThreaderBase::Pointer = SmartPointer<Self>

Definition at line 69 of file itkMultiThreaderBase.h.

using itk::MultiThreaderBase::Self = MultiThreaderBase

Standard class type aliases.

Definition at line 67 of file itkMultiThreaderBase.h.

using itk::MultiThreaderBase::Superclass = Object

Definition at line 68 of file itkMultiThreaderBase.h.

template<unsigned int VDimension>

using itk::MultiThreaderBase::TemplatedThreadingFunctorType = std::function<void(const ImageRegion<VDimension> &)>

Definition at line 245 of file itkMultiThreaderBase.h.

using itk::MultiThreaderBase::ThreadingFunctorType = std::function<void( const IndexValueType index[], const SizeValueType size[])>

Definition at line 248 of file itkMultiThreaderBase.h.

Member Enumeration Documentation

enum itk::MultiThreaderBase::ThreaderType

Currently supported types of multi-threader implementations. Last will change with additional implementations.

Enumerator
Platform
First
Pool
TBB
Last
Unknown

Definition at line 112 of file itkMultiThreaderBase.h.

Constructor & Destructor Documentation

itk::MultiThreaderBase::MultiThreaderBase ( )

protected

The number of work units to create.

itk::MultiThreaderBase::~MultiThreaderBase ( )

overrideprotected

The number of work units to create.

Member Function Documentation

static ThreadIdType itk::MultiThreaderBase::GetGlobalDefaultNumberOfThreads ( )

static

Set/Get the value which is used to initialize the NumberOfThreads in the constructor. It will be clamped to the range [1, m_GlobalMaximumNumberOfThreads ]. Therefore the caller of this method should check that the requested number of threads was accepted.

static ThreadIdType itk::MultiThreaderBase::GetGlobalDefaultNumberOfThreadsByPlatform ( )

staticprivate

Platform specific number of threads

static ThreaderType itk::MultiThreaderBase::GetGlobalDefaultThreader ( )

static

Set/Get whether the default multi-threader implementation.

The default multi-threader type is picked up from ITK_GLOBAL_DEFAULT_THREADER
environment variable. Example ITK_GLOBAL_DEFAULT_THREADER=TBB
A deprecated ITK_USE_THREADPOOL environment variable is also examined,
but it can only choose Pool or Platform multi-threader.
Platform multi-threader should be avoided,
as it introduces the biggest overhead.

If the SetGlobalDefaultThreaderType API is ever used by the developer,
the developer's choice is respected over the environment variables.

static ThreadIdType itk::MultiThreaderBase::GetGlobalMaximumNumberOfThreads ( )

static

Set/Get the maximum number of threads to use when multithreading. It will be clamped to the range [ 1, ITK_MAX_THREADS ] because several arrays are already statically allocated using the ITK_MAX_THREADS number. Therefore the caller of this method should check that the requested number of threads was accepted.

virtual ThreadIdType itk::MultiThreaderBase::GetMaximumNumberOfThreads ( ) const

virtual

Get/Set the number of threads to use. It will be clamped to the range [ 1, m_GlobalMaximumNumberOfThreads ], so the caller of this method should check that the requested number of threads was accepted.

virtual const char* itk::MultiThreaderBase::GetNameOfClass ( ) const

virtual

Run-time type information (and related methods).

Reimplemented from itk::Object.

Reimplemented in itk::PoolMultiThreader, and itk::TBBMultiThreader.

virtual ThreadIdType itk::MultiThreaderBase::GetNumberOfWorkUnits ( ) const

virtual

Get/Set the number of work units to create. It might be clamped to the range [ 1, SomeMaximumNumber ], so the caller of this method should check that the requested number of work units was accepted.

static void itk::MultiThreaderBase::HandleFilterProgress	(	ProcessObject *	filter,
		float	progress = `-1.0f`
	)

static

Updates progress if progress is non-negative and checks for abort. If "abort generate data" is set, throws the ProcessAborted exception.

Referenced by ParallelizeImageRegionRestrictDirection().

itk::MultiThreaderBase::itkGetGlobalDeclarationMacro	(	MultiThreaderBaseGlobals	,
		PimplGlobals
	)

private

Only used to synchronize the global variable across static libraries.

itk::MultiThreaderBase::itkLegacyMacro ( static void SetGlobalDefaultUseThreadPoolconst bool GlobalDefaultUseThreadPool )

Set/Get whether to use the to use the thread pool implementation or the spawing implementation of starting threads.

Deprecated: use Get/Set GlobalDefaultThreader.

itk::MultiThreaderBase::itkLegacyMacro ( static bool GetGlobalDefaultUseThreadPool() )

Set/Get whether to use the to use the thread pool implementation or the spawing implementation of starting threads.

Deprecated: use Get/Set GlobalDefaultThreader.

static Pointer itk::MultiThreaderBase::New ( )

static

Method for creation through the object factory.

Examples:: SphinxExamples/src/Core/Common/FilterAndParallelizeImageRegion/Code.cxx, and SphinxExamples/src/Core/Common/UseParallelizeImageRegion/Code.cxx.

virtual void itk::MultiThreaderBase::ParallelizeArray	(	SizeValueType	firstIndex,
		SizeValueType	lastIndexPlus1,
		ArrayThreadingFunctorType	aFunc,
		ProcessObject *	filter
	)

virtual

Parallelize an operation over an array. If filter argument is not nullptr, this function will update its progress as each index is completed.

This implementation simply delegates parallelization to the old interface SetSingleMethod+SingleMethodExecute. This method is meant to be overloaded!

Reimplemented in itk::PoolMultiThreader, and itk::TBBMultiThreader.

static ITK_THREAD_RETURN_FUNCTION_CALL_CONVENTION itk::MultiThreaderBase::ParallelizeArrayHelper ( void * arg )

staticprotected

The number of work units to create.

template<unsigned int VDimension>

ITK_TEMPLATE_EXPORT void itk::MultiThreaderBase::ParallelizeImageRegion	(	const ImageRegion< VDimension > &	requestedRegion,
		TemplatedThreadingFunctorType< VDimension >	funcP,
		ProcessObject *	filter
	)

inline

Break up region into smaller chunks, and call the function with chunks as parameters. If filter argument is not nullptr, this function will update its progress as each work unit is completed. Delegates work to non-templated version.

Definition at line 267 of file itkMultiThreaderBase.h.

References itk::ImageRegion< VImageDimension >::GetIndex(), itk::ImageRegion< VImageDimension >::GetSize(), itk::Size< VDimension >::m_InternalArray, itk::Index< VDimension >::m_InternalArray, itk::ImageRegion< VImageDimension >::SetIndex(), and itk::ImageRegion< VImageDimension >::SetSize().

virtual void itk::MultiThreaderBase::ParallelizeImageRegion	(	unsigned int	dimension,
		const IndexValueType	index[],
		const SizeValueType	size[],
		ThreadingFunctorType	funcP,
		ProcessObject *	filter
	)

virtual

Break up region into smaller chunks, and call the function with chunks as parameters. This overload does the actual work and should be implemented by derived classes.

Reimplemented in itk::PoolMultiThreader, and itk::TBBMultiThreader.

static ITK_THREAD_RETURN_FUNCTION_CALL_CONVENTION itk::MultiThreaderBase::ParallelizeImageRegionHelper ( void * arg )

staticprotected

The number of work units to create.

template<unsigned int VDimension>

ITK_TEMPLATE_EXPORT void itk::MultiThreaderBase::ParallelizeImageRegionRestrictDirection	(	unsigned int	restrictedDirection,
		const ImageRegion< VDimension > &	requestedRegion,
		TemplatedThreadingFunctorType< VDimension >	funcP,
		ProcessObject *	filter
	)

inline

Similar to ParallelizeImageRegion, but do not split the region along one of the directions. If VDimension is 1, restrictedDirection is ignored and no parallelization occurs.

Definition at line 293 of file itkMultiThreaderBase.h.

References itk::ImageRegion< VImageDimension >::GetIndex(), itk::ImageRegion< VImageDimension >::GetSize(), HandleFilterProgress(), itk::ImageRegion< VImageDimension >::SetIndex(), and itk::ImageRegion< VImageDimension >::SetSize().

void itk::MultiThreaderBase::PrintSelf	(	std::ostream &	os,
		Indent	indent
	)		const

overrideprotectedvirtual

The number of work units to create.

Reimplemented from itk::LightObject.

Reimplemented in itk::PoolMultiThreader, and itk::TBBMultiThreader.

static void itk::MultiThreaderBase::SetGlobalDefaultNumberOfThreads ( ThreadIdType val )

static

Set/Get the value which is used to initialize the NumberOfThreads in the constructor. It will be clamped to the range [1, m_GlobalMaximumNumberOfThreads ]. Therefore the caller of this method should check that the requested number of threads was accepted.

static void itk::MultiThreaderBase::SetGlobalDefaultThreader ( ThreaderType threaderType )

static

Set/Get whether the default multi-threader implementation.

The default multi-threader type is picked up from ITK_GLOBAL_DEFAULT_THREADER
environment variable. Example ITK_GLOBAL_DEFAULT_THREADER=TBB
A deprecated ITK_USE_THREADPOOL environment variable is also examined,
but it can only choose Pool or Platform multi-threader.
Platform multi-threader should be avoided,
as it introduces the biggest overhead.

If the SetGlobalDefaultThreaderType API is ever used by the developer,
the developer's choice is respected over the environment variables.

static void itk::MultiThreaderBase::SetGlobalMaximumNumberOfThreads ( ThreadIdType val )

static

Set/Get the maximum number of threads to use when multithreading. It will be clamped to the range [ 1, ITK_MAX_THREADS ] because several arrays are already statically allocated using the ITK_MAX_THREADS number. Therefore the caller of this method should check that the requested number of threads was accepted.

virtual void itk::MultiThreaderBase::SetMaximumNumberOfThreads ( ThreadIdType numberOfThreads )

virtual

Get/Set the number of threads to use. It will be clamped to the range [ 1, m_GlobalMaximumNumberOfThreads ], so the caller of this method should check that the requested number of threads was accepted.

Reimplemented in itk::PoolMultiThreader.

virtual void itk::MultiThreaderBase::SetNumberOfWorkUnits ( ThreadIdType numberOfWorkUnits )

virtual

Get/Set the number of work units to create. It might be clamped to the range [ 1, SomeMaximumNumber ], so the caller of this method should check that the requested number of work units was accepted.

Reimplemented in itk::TBBMultiThreader.

virtual void itk::MultiThreaderBase::SetSingleMethod	(	ThreadFunctionType	,
		void *	data
	)

pure virtual

Set the SingleMethod to f() and the UserData field of the WorkUnitInfo that is passed to it will be data. This method must be of type itkThreadFunctionType and must take a single argument of type void *.

Implemented in itk::PoolMultiThreader, and itk::TBBMultiThreader.

virtual void itk::MultiThreaderBase::SingleMethodExecute ( )

pure virtual

Execute the SingleMethod (as define by SetSingleMethod) using m_NumberOfWorkUnits threads. As a side effect the m_NumberOfWorkUnits will be checked against the current m_GlobalMaximumNumberOfThreads and clamped if necessary.

Implemented in itk::PoolMultiThreader, and itk::TBBMultiThreader.

static ITK_THREAD_RETURN_FUNCTION_CALL_CONVENTION itk::MultiThreaderBase::SingleMethodProxy ( void * arg )

staticprotected

Static function used as a "proxy callback" by multi-threaders. The threading library will call this routine for each thread, which will delegate the control to the prescribed SingleMethod. This routine acts as an intermediary between the multi-threaders and the user supplied callback (SingleMethod) in order to catch any exceptions thrown by the threads.

static ThreaderType itk::MultiThreaderBase::ThreaderTypeFromString ( std::string threaderString )

static

Convert a threader name into its enum type.

static std::string itk::MultiThreaderBase::ThreaderTypeToString ( ThreaderType threader )

inlinestatic

Convert a threader enum type into a string for displaying or logging.

Definition at line 118 of file itkMultiThreaderBase.h.

Friends And Related Function Documentation

friend class ProcessObject

friend

Friends of Multithreader. ProcessObject is a friend so that it can call PrintSelf() on its Multithreader.

Friends of DataObject

Definition at line 427 of file itkMultiThreaderBase.h.

Member Data Documentation

ThreadIdType itk::MultiThreaderBase::m_MaximumNumberOfThreads

protected

The number of threads to use. The m_MaximumNumberOfThreads must always be less than or equal to the m_GlobalMaximumNumberOfThreads before it is used during the execution of a threaded method. Its value is initialized to m_GlobalDefaultNumberOfThreads at construction time. Its value is clamped to the current m_GlobalMaximumNumberOfThreads in the SingleMethodExecute() method.

Definition at line 402 of file itkMultiThreaderBase.h.

ThreadIdType itk::MultiThreaderBase::m_NumberOfWorkUnits

protected

The number of work units to create.

Definition at line 392 of file itkMultiThreaderBase.h.

MultiThreaderBaseGlobals* itk::MultiThreaderBase::m_PimplGlobals

staticprivate

The number of work units to create.

Definition at line 423 of file itkMultiThreaderBase.h.

void* itk::MultiThreaderBase::m_SingleData

protected

The data to be passed as argument.

Definition at line 416 of file itkMultiThreaderBase.h.

ThreadFunctionType itk::MultiThreaderBase::m_SingleMethod

protected

The method to invoke.

Definition at line 413 of file itkMultiThreaderBase.h.

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

itkMultiThreaderBase.h

Detailed Description

Classes

Public Types

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation