ThreadInterface Class Reference

#include <thread.h>

Inheritance diagram for ThreadInterface:

Detailed Description

Basic thread template. The ThreadInterface is derived from JobInterface but has its own private thread and therefore you can immediately start it using Start() or Run().

One way to create a thread is to inherit from ThreadInterface/ThreadInterfaceTemplate and to implement GetName() and operator (), for example

class MyThread : public ThreadInterfaceTemplate<MyThread>
{
public:
const char* GetName() const { return "MyThread"; }
Result<void> operator ()()
{
... your code goes here ...
... don't forget to check IsCancelled() and return OK or an error ...
}
};
const Char * GetName() const
Definition: job.h:179

A thread is reference counted. If you all you want to do is start it, you can create it with NewObj(), check the return value and call Start(). This will automatically delete your thread object once it finished and is not referenced anymore. If your thread performs potentially lengthy operations in a loop it must call IsCancelled() periodically.

Threads are reference-counted and you must not create an instance on the stack or as member variable of a class. You can create a thread using NewObj or via ThreadRef::Run() or ThreadRef::Create().

Public Member Functions

 ThreadInterface (const JobInterfaceJumpTablePOD &jmpTable)
 
 ThreadInterface (ThreadInterface &&src)
 
Bool IsRunning () const
 
Bool Wait (TimeValue timeout=TIMEVALUE_INFINITE, WAITMODE mode=WAITMODE::DEFAULT) const
 
Result< void > Start (THREADPRIORITY priority=THREADPRIORITY::NORMAL)
 
String ToString (const FormatStatement *formatStatement=nullptr) const
 
Result< void > PrivateResetState ()
 
- Public Member Functions inherited from JobInterface
JOBOPTIONFLAGS GetJobOptions () const
 
const CharGetName () const
 
 JobInterface (const JobInterfaceJumpTablePOD &jmpTable)
 
 ~JobInterface ()
 
 JobInterface (JobInterface &&src)
 
JobInterfaceoperator= (JobInterface &&src)
 
Bool Wait (TimeValue timeout=TIMEVALUE_INFINITE, WAITMODE mode=WAITMODE::DEFAULT) const
 
Result< void > GetResult (TimeValue timeout=TIMEVALUE_INFINITE, WAITMODE mode=WAITMODE::DEFAULT) const
 
Result< void > MoveResult (TimeValue timeout=TIMEVALUE_INFINITE, WAITMODE mode=WAITMODE::DEFAULT)
 
void Cancel ()
 
Bool IsCancelled () const
 
void CancelAndWait (WAITMODE mode=WAITMODE::DEFAULT)
 
JobInterfaceEnqueue (JobQueueInterface *queue=JOBQUEUE_CURRENT)
 
Result< void > AddSubJob (JobInterface *subJob)
 
template<typename JOB >
Result< void > AddSubJob (ResultMemT< JOB * > subJob)
 
template<typename JOBREF >
Result< void > AddSubJob (ResultMemT< JOBREF > &&subJob)
 
template<typename GROUP >
Result< void > AddSubGroup (GROUP *subGroup)
 
template<typename GROUP >
Result< void > AddSubGroup (ResultMemT< GROUP * > subGroup)
 
template<typename GROUP >
Result< void > AddSubGroup (ResultMemT< GROUP > subGroup)
 
JobGroupInterfaceGetJobGroup () const
 
ObservableFinishedBase< JobInterfaceObservableFinished ()
 
ObservableCancelledBase< JobInterfaceObservableCancelled ()
 
Result< void > Then (JobInterface *next, JobQueueInterface *queue=JOBQUEUE_CURRENT)
 
String ToString (const FormatStatement *formatStatement=nullptr) const
 

Static Public Member Functions

static const ThreadInterfaceGetCurrentThread ()
 
static Bool IsMainThread ()
 
static THREADTYPE GetCurrentThreadType ()
 
static THREADTYPE GetCurrentThreadType (Int &threadIdentifier)
 
static Result< void > AssimilateAlienThread ()
 
- Static Public Member Functions inherited from JobInterface
static Int GetCurrentWorkerThreadIndex ()
 
static Int GetCurrentThreadCount ()
 
static Bool IsCurrentJobCancelled (const JobInterface *optionalJob=nullptr)
 
static JobStatusInterfaceGetCurrentJob ()
 

Constructor & Destructor Documentation

◆ ThreadInterface() [1/2]

ThreadInterface ( const JobInterfaceJumpTablePOD &  jmpTable)
explicit
Parameters
[in]jmpTableJump table of the implementation class.

◆ ThreadInterface() [2/2]

Member Function Documentation

◆ IsRunning()

Bool IsRunning ( ) const

Checks whether this thread is currently running. Use Wait() if you have to wait for a thread to finish. Repeatedly calling this method will be detected and result in a debug break. THREADSAFE.

Returns
False if the thread wasn't running anymore.

◆ Wait()

Bool Wait ( TimeValue  timeout = TIMEVALUE_INFINITE,
WAITMODE  mode = WAITMODE::DEFAULT 
) const

Waits until this thread has been executed. As long as a thread hasn't been started it is considered not to have finished yet. Once it has run this will return immediately until you restart the thread.

Wait() might execute other jobs in the current queue until the one you are waiting for has finished or is timed out. Therefore you may never lock a shared resource another job might use as well and then wait. For one this could dead-lock and conceptually this would result in single-threaded performance.

If you call Wait() from within an enqueued job you must have started what you are waiting for. Otherwise Wait() will immediately return false because this would lead to a deadlock. The same applies if a thread tries to wait for itself.

Instead of waiting for a thread to start some action after it has finished you can subscribe to ObservableFinished(). This cannot dead-lock, is more efficient and can even be used to run the observer in a different queue. For example you can run a thread and register an observer for it that will run on the main thread's queue and updates the UI. THREADSAFE.

Parameters
[in]timeoutMaximum wait interval (or TIMEVALUE_INFINITE for no time-out).
[in]modeWAITMODE::DEFAULT by default. WAITMODE::RETURN_ON_CANCEL means that Wait() will return if the caller has been cancelled even if the condition has not been set yet.
Returns
True if successful, false if you try to wait inside an enqueued job.

◆ Start()

Result<void> Start ( THREADPRIORITY  priority = THREADPRIORITY::NORMAL)

Starts a thread to execute this job's worker method (will add a reference and remove it when the object is no longer needed). If you try to start an already running thread this will fail and return an error.

Parameters
[in]priorityTHREADPRIORITY::NORMAL or THREADPRIORITY::BELOW for a background thread.
Returns
OK on success. Failse if the thread is already running or no more threads are available.

◆ GetCurrentThread()

static const ThreadInterface* GetCurrentThread ( )
static

Returns a pointer to the currently running thread. If you call this from a job or a thread you have created by using OS APIs a nullptr is returned. THREADSAFE.

Returns
This thread's ThreadInterface* or nullptr (worker, main or other OS thread)

◆ IsMainThread()

static Bool IsMainThread ( )
static

Checks if this thread is the main application thread. THREADSAFE.

Returns
True if this is the main application thread.

◆ GetCurrentThreadType() [1/2]

static THREADTYPE GetCurrentThreadType ( )
static

Returns information about the current thread. THREADSAFE.

Returns
See THREADTYPE.

◆ GetCurrentThreadType() [2/2]

static THREADTYPE GetCurrentThreadType ( Int threadIdentifier)
static

Returns information about the current thread. THREADSAFE.

Parameters
[out]threadIdentifierFor THREADTYPE::WORKER the the index of the worker thread is returned, for THREADTYPE::MAIN 0 is returned if it currently executes jobs. Otherwise this is an opaque identifier for the current thread.
Returns
See THREADTYPE.

◆ AssimilateAlienThread()

static Result<void> AssimilateAlienThread ( )
static

Allocates internal resources for an alien thread (CoreThread, unique thread index and so on). THREADSAFE.

Returns
OK on success.

◆ ToString()

String ToString ( const FormatStatement formatStatement = nullptr) const

Returns a readable string of the content.

Parameters
[in]formatStatementNullptr or additional formatting instruction. Currently no additional formatting instructions are supported.
Returns
The converted result.

◆ PrivateResetState()

Result<void> PrivateResetState ( )