The interface class for the controller for worker threads and jobs. More...

#include <Thread.h>

Inheritance diagram for Nektar::Thread::ThreadManager:

Public Member Functions
virtual	~ThreadManager ()
	Destructor. More...

void	QueueJobs (std::vector< ThreadJob * > &joblist)
	Pass a list of tasklets to the master queue. More...

void	QueueJob (ThreadJob *job)
	Pass a single job to the master queue. More...

unsigned int	GetNumWorkers ()
	Return the number of active workers. More...

unsigned int	GetWorkerNum ()
	Returns the worker number of the executing thread. More...

void	SetNumWorkers (const unsigned int num)
	Sets the number of active workers. More...

void	SetNumWorkers ()
	Sets the number of active workers to the maximum. More...

unsigned int	GetMaxNumWorkers ()
	Gets the maximum available number of threads. More...

void	Wait ()
	Waits until all queued jobs are finished. More...

void	SetChunkSize (unsigned int chnk)
	Controls how many jobs are sent to each worker at a time. More...

void	SetSchedType (SchedType s)
	Sets the current scheduling algorithm. More...

bool	InThread ()
	Indicates whether the code is in a worker thread or not. More...

void	Hold ()
	A calling threads holds until all active threads call this method. More...

const std::string &	GetType ()
	Returns a description of the type of threading. More...

bool	IsInitialised ()
	ThreadManager implementation. More...

int	GetThrFromPartition (int pPartition)

int	GetRankFromPartition (int pPartition)

int	GetPartitionFromRankThr (int pRank, unsigned int pThr)

Protected Member Functions
virtual void	v_QueueJobs (std::vector< ThreadJob * > &joblist)=0

virtual void	v_QueueJob (ThreadJob *job)=0

virtual unsigned int	v_GetNumWorkers ()=0

virtual unsigned int	v_GetWorkerNum ()=0

virtual void	v_SetNumWorkers (const unsigned int num)=0

virtual void	v_SetNumWorkers ()=0

virtual unsigned int	v_GetMaxNumWorkers ()=0

virtual void	v_Wait ()=0

virtual void	v_SetChunkSize (unsigned int chnk)=0

virtual void	v_SetSchedType (SchedType s)=0

virtual bool	v_InThread ()=0

virtual void	v_Hold ()=0

virtual const std::string &	v_GetType () const =0

virtual bool	v_IsInitialised ()

Detailed Description

The interface class for the controller for worker threads and jobs.

There may be multiple instances of implementations of this class. They are instantiated by ThreadMaster::CreateInstance(string, int). Use ThreadMaster::GetInstance(string) to get a pointer to the instance. Each ThreadManager is associated in ThreadMaster with a string.

Jobs are sent to the worker threads by placing them in the queue with QueueJob() and QueueJobs(). Jobs may be run in indeterminate order. Jobs are permitted to run immediately they are queued. If this is not desired set the number of active workers to 0 until all jobs are queued.

Jobs are taken from the master queue by active worker threads.

We have the concept of the master thread. This is the thread that instantiates the ThreadManager, calls QueueJob(), Wait() and so on. This thread must be included in the number of threads started when the ThreadManager is created, so that no more than this number of threads are ever executing work at any time. The master thread is assumed to be working unless it is in Wait().

Thus if the ThreadManager is called with CreateInstance(string s, int N) there should be N threads /em including the master thread. If the master thread calls Wait() (which causes the master thread to sleep until the job queue is empty) then the master thread should become available to run jobs from the queue.

Only the master thread should call ThreadManager methods. Although it should always be possible for code to identify whether it's the master thread (through design) there is a InThread() method that returns true if the thread is a worker.

Definition at line 159 of file Thread.h.

Constructor & Destructor Documentation

◆ ~ThreadManager()

Nektar::Thread::ThreadManager::~ThreadManager ( )

virtual

Destructor.

Should stop worker threads and clean up. This shouldn't be called until the program is exiting anyway, some implementations may need to unlock threads to allow clean exit.

Definition at line 102 of file Thread.cpp.

{
    // empty
}

Member Function Documentation

◆ GetMaxNumWorkers()

unsigned int Nektar::Thread::ThreadManager::GetMaxNumWorkers ( )

inline

Gets the maximum available number of threads.

Returns: The maximum number of workers.

Definition at line 251 of file Thread.h.

    {
        return v_GetMaxNumWorkers();
    }

References v_GetMaxNumWorkers().

Referenced by GetPartitionFromRankThr(), GetRankFromPartition(), and GetThrFromPartition().

◆ GetNumWorkers()

unsigned int Nektar::Thread::ThreadManager::GetNumWorkers ( )

inline

Return the number of active workers.

Active workers are threads that are either running jobs or are waiting for jobs to be queued.

Definition at line 198 of file Thread.h.

    {
        return v_GetNumWorkers();
    }

References v_GetNumWorkers().

◆ GetPartitionFromRankThr()

int Nektar::Thread::ThreadManager::GetPartitionFromRankThr	(	int	pRank,
		unsigned int	pThr
	)

inline

Definition at line 352 of file Thread.h.

    {
        return pRank * GetMaxNumWorkers() + pThr;
    }

References GetMaxNumWorkers().

◆ GetRankFromPartition()

int Nektar::Thread::ThreadManager::GetRankFromPartition ( int pPartition )

inline

Definition at line 347 of file Thread.h.

    {
        return pPartition / GetMaxNumWorkers();
    }

References GetMaxNumWorkers().

◆ GetThrFromPartition()

int Nektar::Thread::ThreadManager::GetThrFromPartition ( int pPartition )

inline

Definition at line 342 of file Thread.h.

    {
        return pPartition % GetMaxNumWorkers();
    }

References GetMaxNumWorkers().

◆ GetType()

const std::string & Nektar::Thread::ThreadManager::GetType ( )

inline

Returns a description of the type of threading.

E.g. "Threading with Boost"

Definition at line 331 of file Thread.h.

    {
        return v_GetType();
    }

References v_GetType().

◆ GetWorkerNum()

unsigned int Nektar::Thread::ThreadManager::GetWorkerNum ( )

inline

Returns the worker number of the executing thread.

Returns an unsigned int between 0 and N-1 where N is the number of active worker threads. Repeated calls from within this thread will always return the same value and the value will be the same as returned from ThreadJob.GetWorkerNum(). The same thread will run a job until it finishes.

Although if there are active threads then thread 0 is always one of them, it is possible that thread 0 does not run for a given set of jobs. For example, if there are 4 active threads and 3 jobs are submitted with a e_static scheduling strategy and a chunksize of 1, then it is possible that threads 1,2, and 3 pick up the jobs and thread 0 remains idle.

Returns 0 if called by non-thread.

Definition at line 220 of file Thread.h.

    {
        return v_GetWorkerNum();
    }

References v_GetWorkerNum().

◆ Hold()

void Nektar::Thread::ThreadManager::Hold ( )

inline

A calling threads holds until all active threads call this method.

When called, the calling thread will sleep until all active workers have called this method. Once all have done so all threads awake and continue execution.

Note: Behaviour is likely undefined if the number of active workers is altered after a thread has called this method. It is only safe to call SetNumWorkers() when no threads are holding.

Definition at line 322 of file Thread.h.

    {
        v_Hold();
    }

References v_Hold().

◆ InThread()

bool Nektar::Thread::ThreadManager::InThread ( )

inline

Indicates whether the code is in a worker thread or not.

Returns: True if the caller is in a worker thread.

Definition at line 306 of file Thread.h.

    {
        return v_InThread();
    }

References v_InThread().

◆ IsInitialised()

bool Nektar::Thread::ThreadManager::IsInitialised ( )

inline

ThreadManager implementation.

Definition at line 337 of file Thread.h.

    {
        return v_IsInitialised();
    }

References v_IsInitialised().

◆ QueueJob()

void Nektar::Thread::ThreadManager::QueueJob ( ThreadJob * job )

inline

Pass a single job to the master queue.

Parameters

job	A pointer to a ThreadJob subclass.

The job may become available for running immediately. If this is an issue then suspend the workers with SetNumWorkers(0) until the jobs are queued.

Definition at line 188 of file Thread.h.

    {
        v_QueueJob(job);
    }

References v_QueueJob().

Referenced by Nektar::Thread::ThreadManagerStd::v_QueueJobs().

◆ QueueJobs()

void Nektar::Thread::ThreadManager::QueueJobs ( std::vector< ThreadJob * > & joblist )

inline

Pass a list of tasklets to the master queue.

Parameters

joblist Vector of ThreadJob pointers.

The list of jobs is copied into the master queue. Jobs may be available for running immediately, even before the list has been fully copied. This can have consequences for the scheduling. If this is an issue then suspend the workers with SetNumWorkers(0) until the jobs are queued.

See also: SchedType

Definition at line 176 of file Thread.h.

    {
        v_QueueJobs(joblist);
    }

References v_QueueJobs().

◆ SetChunkSize()

void Nektar::Thread::ThreadManager::SetChunkSize ( unsigned int chnk )

inline

Controls how many jobs are sent to each worker at a time.

The exact meaning of this parameter depends on the current scheduling algorithm.

See also: SchedType; SetSchedType()

Definition at line 290 of file Thread.h.

    {
        v_SetChunkSize(chnk);
    }

References v_SetChunkSize().

◆ SetNumWorkers() [1/2]

void Nektar::Thread::ThreadManager::SetNumWorkers ( )

inline

Sets the number of active workers to the maximum.

Sets the number of active workers to the maximum available.

Definition at line 243 of file Thread.h.

    {
        v_SetNumWorkers();
    }

References v_SetNumWorkers().

◆ SetNumWorkers() [2/2]

void Nektar::Thread::ThreadManager::SetNumWorkers ( const unsigned int num )

inline

Sets the number of active workers.

Parameters

num	The number of active workers.

Active workers are threads that are either running jobs or are waiting for jobs to be queued.

If num is greater than the maximum allowed number of active workers, then the maximum value will be used instead.

Definition at line 234 of file Thread.h.

    {
        v_SetNumWorkers(num);
    }

References v_SetNumWorkers().

◆ SetSchedType()

void Nektar::Thread::ThreadManager::SetSchedType ( SchedType s )

inline

Sets the current scheduling algorithm.

See also: SetChunkSize()

Definition at line 298 of file Thread.h.

    {
        v_SetSchedType(s);
    }

References v_SetSchedType().

◆ v_GetMaxNumWorkers()

virtual unsigned int Nektar::Thread::ThreadManager::v_GetMaxNumWorkers ( )

protectedpure virtual

Implemented in Nektar::Thread::ThreadStartupManager, and Nektar::Thread::ThreadManagerStd.

Referenced by GetMaxNumWorkers().

◆ v_GetNumWorkers()

virtual unsigned int Nektar::Thread::ThreadManager::v_GetNumWorkers ( )

protectedpure virtual

Implemented in Nektar::Thread::ThreadStartupManager, and Nektar::Thread::ThreadManagerStd.

Referenced by GetNumWorkers().

◆ v_GetType()

virtual const std::string & Nektar::Thread::ThreadManager::v_GetType ( ) const

protectedpure virtual

Implemented in Nektar::Thread::ThreadStartupManager, and Nektar::Thread::ThreadManagerStd.

Referenced by GetType().

◆ v_GetWorkerNum()

virtual unsigned int Nektar::Thread::ThreadManager::v_GetWorkerNum ( )

protectedpure virtual

Implemented in Nektar::Thread::ThreadStartupManager, and Nektar::Thread::ThreadManagerStd.

Referenced by GetWorkerNum().

◆ v_Hold()

virtual void Nektar::Thread::ThreadManager::v_Hold ( )

protectedpure virtual

Implemented in Nektar::Thread::ThreadStartupManager, and Nektar::Thread::ThreadManagerStd.

Referenced by Hold().

◆ v_InThread()

virtual bool Nektar::Thread::ThreadManager::v_InThread ( )

protectedpure virtual

Implemented in Nektar::Thread::ThreadStartupManager, and Nektar::Thread::ThreadManagerStd.

Referenced by InThread().

◆ v_IsInitialised()

bool Nektar::Thread::ThreadManager::v_IsInitialised ( )

protectedvirtual

Implementations should not override this function, since they are initialised.

Returns: True if this ThreadManager has been initialised.

Reimplemented in Nektar::Thread::ThreadStartupManager.

Definition at line 91 of file Thread.cpp.

{
    return true;
}

Referenced by IsInitialised().

◆ v_QueueJob()

virtual void Nektar::Thread::ThreadManager::v_QueueJob ( ThreadJob * job )

protectedpure virtual

Implemented in Nektar::Thread::ThreadStartupManager, and Nektar::Thread::ThreadManagerStd.

Referenced by QueueJob().

◆ v_QueueJobs()

virtual void Nektar::Thread::ThreadManager::v_QueueJobs ( std::vector< ThreadJob * > & joblist )

protectedpure virtual

Implemented in Nektar::Thread::ThreadStartupManager, and Nektar::Thread::ThreadManagerStd.

Referenced by QueueJobs().

◆ v_SetChunkSize()

virtual void Nektar::Thread::ThreadManager::v_SetChunkSize ( unsigned int chnk )

protectedpure virtual

Implemented in Nektar::Thread::ThreadStartupManager, and Nektar::Thread::ThreadManagerStd.

Referenced by SetChunkSize().

◆ v_SetNumWorkers() [1/2]

virtual void Nektar::Thread::ThreadManager::v_SetNumWorkers ( )

protectedpure virtual

Implemented in Nektar::Thread::ThreadStartupManager, and Nektar::Thread::ThreadManagerStd.

Referenced by SetNumWorkers().

◆ v_SetNumWorkers() [2/2]

virtual void Nektar::Thread::ThreadManager::v_SetNumWorkers ( const unsigned int num )

protectedpure virtual

Implemented in Nektar::Thread::ThreadStartupManager, and Nektar::Thread::ThreadManagerStd.

◆ v_SetSchedType()

virtual void Nektar::Thread::ThreadManager::v_SetSchedType ( SchedType s )

protectedpure virtual

Implemented in Nektar::Thread::ThreadStartupManager, and Nektar::Thread::ThreadManagerStd.

Referenced by SetSchedType().

◆ v_Wait()

virtual void Nektar::Thread::ThreadManager::v_Wait ( )

protectedpure virtual

Implemented in Nektar::Thread::ThreadStartupManager, and Nektar::Thread::ThreadManagerStd.

Referenced by Wait().

◆ Wait()

void Nektar::Thread::ThreadManager::Wait ( )

inline

Waits until all queued jobs are finished.

If there are no jobs running or queued this method returns immediately. Otherwise it blocks until the queue is empty and the worker threads are idle.

Implementations must ensure that trivial deadlocks are not possible from this method, that is, that this code:

// assume ThreadManager* tm
// assume SomeJob is subclass of ThreadJob
// assume SomeJob job
 
tm->SetNumWorkers(0);
tm->QueueJob(job);
tm->Wait();

does not wait forever. Since the master thread is counted in the number of worker threads, implementations should increase the number of active workers by 1 on entering Wait().

Definition at line 277 of file Thread.h.

    {
        v_Wait();
    }

References v_Wait().

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~ThreadManager()

Member Function Documentation

◆ GetMaxNumWorkers()

◆ GetNumWorkers()

◆ GetPartitionFromRankThr()

◆ GetRankFromPartition()

◆ GetThrFromPartition()

◆ GetType()

◆ GetWorkerNum()

◆ Hold()

◆ InThread()

◆ IsInitialised()

◆ QueueJob()

◆ QueueJobs()

◆ SetChunkSize()

◆ SetNumWorkers() [1/2]

◆ SetNumWorkers() [2/2]

◆ SetSchedType()

◆ v_GetMaxNumWorkers()

◆ v_GetNumWorkers()

◆ v_GetType()

◆ v_GetWorkerNum()

◆ v_Hold()

◆ v_InThread()

◆ v_IsInitialised()

◆ v_QueueJob()

◆ v_QueueJobs()

◆ v_SetChunkSize()

◆ v_SetNumWorkers() [1/2]

◆ v_SetNumWorkers() [2/2]

◆ v_SetSchedType()

◆ v_Wait()

◆ Wait()