#include <thread.h>
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
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().
Static Public Member Functions | |
| static const ThreadInterface * | GetCurrentThread () |
| 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 JobStatusInterface * | GetCurrentJob () |
Constructor & Destructor Documentation
◆ ThreadInterface() [1/2]
|
explicit |
- Parameters
-
[in] jmpTable Jump table of the implementation class.
◆ ThreadInterface() [2/2]
| ThreadInterface | ( | ThreadInterface && | src | ) |
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] timeout Maximum wait interval (or TIMEVALUE_INFINITE for no time-out). [in] mode WAITMODE::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] priority THREADPRIORITY::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 |
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 |
Checks if this thread is the main application thread. THREADSAFE.
- Returns
- True if this is the main application thread.
◆ GetCurrentThreadType() [1/2]
|
static |
Returns information about the current thread. THREADSAFE.
- Returns
- See THREADTYPE.
◆ GetCurrentThreadType() [2/2]
|
static |
Returns information about the current thread. THREADSAFE.
- Parameters
-
[out] threadIdentifier For 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 |
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] formatStatement Nullptr or additional formatting instruction. Currently no additional formatting instructions are supported.
- Returns
- The converted result.
◆ PrivateResetState()
| Result<void> PrivateResetState | ( | ) |