ThreadRefTemplate< INTERFACE > Class Template Reference

#include <thread.h>

Inheritance diagram for ThreadRefTemplate< INTERFACE >:

Detailed Description

template<typename INTERFACE>
class maxon::ThreadRefTemplate< INTERFACE >

Reference to a thread (ThreadInterface).

Template Parameters
INTERFACEInterface class for the ThreadRef (inherits from ThreadInterface).

Public Member Functions

 MAXON_DEFAULT_REFERENCE_CONSTRUCTORS (ThreadRefTemplate, Ptr)
 
MAXON_IMPLICIT ThreadRefTemplate (const Ptr &src)
 
MAXON_IMPLICIT ThreadRefTemplate (Ptr &&src)
 
Bool IsRunning () const
 
Bool Wait (TimeValue timeout=TIMEVALUE_INFINITE, WAITMODE mode=WAITMODE::DEFAULT) const
 
Result< void > GetResult (TimeValue timeout=TIMEVALUE_INFINITE, WAITMODE mode=WAITMODE::DEFAULT) const
 
void Cancel ()
 
Bool IsCancelled () const
 
void CancelAndWait (WAITMODE mode=WAITMODE::DEFAULT)
 
Result< void > Start (THREADPRIORITY priority=THREADPRIORITY::NORMAL)
 
ObservableFinishedBase< INTERFACE > ObservableFinished ()
 
String ToString (const FormatStatement *formatStatement) const
 
Bool operator== (const ThreadRefTemplate &other) const
 
Bool operator!= (const ThreadRefTemplate &other) const
 
- Public Member Functions inherited from BaseRef< T, HANDLER >
T * GetPointer ()
 
ConstReferencedTypeGetPointer () const
 
T * operator-> ()
 
ConstReferencedTypeoperator-> () const
 
T & operator* ()
 
ConstReferencedTypeoperator* () const
 
 operator T* ()
 
 operator ConstReferencedType * () const
 
 operator Bool () const
 
 operator Bool ()
 
ResultRef< typename std::remove_const< T >::type > MakeWritable (Bool resetOnError=true)
 
 BaseRef ()
 
MAXON_IMPLICIT BaseRef (std::nullptr_t)=delete
 
MAXON_IMPLICIT BaseRef (T *o)
 
template<typename PTR >
 BaseRef (ForwardResultPtr< PTR > o)
 
 BaseRef (ResultPtr< T > o, Int)
 
 BaseRef (const BaseRef &src)
 
template<typename REF , typename = typename std::enable_if<!std::is_base_of<BaseRef, REF>::value && maxon::HasBase<typename REF::ReferencedType, ReferencedType>::value>::type>
MAXON_IMPLICIT BaseRef (const REF &src)
 
template<typename REF , typename = typename std::enable_if<!std::is_base_of<BaseRef, REF>::value && maxon::HasBase<typename REF::ReferencedType, ReferencedType>::value>::type>
MAXON_IMPLICIT BaseRef (REF &src)
 
BaseRefoperator= (T *src)
 
BaseRefoperator= (std::nullptr_t src)
 
BaseRefoperator= (const BaseRef &src)
 
template<typename REF , typename = typename std::enable_if<!std::is_base_of<BaseRef, REF>::value && maxon::HasBase<typename REF::ReferencedType, ReferencedType>::value>::type>
BaseRefoperator= (const REF &src)
 
template<typename REF , typename = typename std::enable_if<!std::is_base_of<BaseRef, REF>::value && maxon::HasBase<typename REF::ReferencedType, ReferencedType>::value>::type>
BaseRefoperator= (REF &src)
 
 BaseRef (BaseRef &&src)
 
template<typename REF , typename = typename std::enable_if<!std::is_const<REF>::value && !std::is_base_of<BaseRef, REF>::value && maxon::HasBase<typename REF::ReferencedType, ReferencedType>::value>::type>
MAXON_IMPLICIT BaseRef (REF &&src)
 
BaseRefoperator= (BaseRef &&src)
 
template<typename REF , typename = typename std::enable_if<!std::is_const<REF>::value && !std::is_base_of<BaseRef, REF>::value && maxon::HasBase<typename REF::ReferencedType, ReferencedType>::value>::type>
BaseRefoperator= (REF &&src)
 
 ~BaseRef ()
 
Bool operator== (const BaseRef &b) const
 
Bool operator!= (const BaseRef &b) const
 
Bool operator== (const T *b) const
 
Bool operator!= (const T *b) const
 
Bool operator== (typename std::remove_const< T >::type *b) const
 
Bool operator!= (typename std::remove_const< T >::type *b) const
 
Bool operator== (std::nullptr_t) const
 
Bool operator!= (std::nullptr_t) const
 
UInt GetHashCode () const
 
T * Disconnect ()
 
void PrivateSetTarget (ResultPtr< T > src)
 

Static Public Member Functions

template<THREADCANCELLATION B = THREADCANCELLATION::AUTOMATIC, typename FN , typename... ARGS>
static auto Create (FN &&src, ARGS &&... args) -> ResultMemT< ThreadResultRef< decltype(src(std::forward< ARGS >(args)...))>>
 
static StrongRef< const INTERFACE > GetCurrentThread ()
 
static Int GetCurrentThreadCount ()
 
static Bool IsMainThread ()
 
static THREADTYPE GetCurrentThreadType ()
 
static Result< void > AssimilateAlienThread ()
 
static Bool IsCurrentThreadCancelled (const ThreadInterface *optionalThread=nullptr)
 
static Bool IsCurrentThreadCancelled (const ThreadRefTemplate< INTERFACE > &optionalThread)
 
template<THREADCANCELLATION B = THREADCANCELLATION::AUTOMATIC, typename FN >
static MAXON_WARN_UNUSED auto Run (FN &&src, THREADPRIORITY priority=THREADPRIORITY::NORMAL) -> ResultMemT< ThreadResultRef< decltype(src())>>
 
template<THREADCANCELLATION B = THREADCANCELLATION::AUTOMATIC, typename FN , typename... ARGS>
static auto Run (FN &&src, THREADPRIORITY priority, ARGS &&... args) -> ResultMemT< ThreadResultRef< decltype(src(std::forward< ARGS >(args)...))>>
 
static const ThreadRefTemplateNullValue ()
 
- Static Public Member Functions inherited from BaseRef< T, HANDLER >
template<typename... ARGS>
static MAXON_ATTRIBUTE_FORCE_INLINE ResultMemT< BaseRefCreate (ARGS &&... args)
 
static const DataTypeGetDataType ()
 
static const BaseRefNullValue ()
 

Private Types

using Ptr = StrongRef< INTERFACE >
 

Private Member Functions

INTERFACE * GCCWorkaroundRun (THREADPRIORITY priority)
 

Static Private Member Functions

template<JOBCANCELLATION B, typename FN , typename... ARGS>
static INTERFACE * CreateThread (FN &&src, ARGS &&... args)
 

Additional Inherited Members

- Public Types inherited from BaseRef< T, HANDLER >
using ReferencedType = T
 
using ConstReferencedType = typename ConstIf< T, Bool(HANDLER::KIND &VALUEKIND::DEEP_CONSTNESS)>::type
 
using DirectlyReferencedType = T
 
using SelfType = BaseRef< T, HANDLER >
 
using Handler = HANDLER
 
using RefCompareType = RefCompare< MAXON_IS_COW_KIND(HANDLER::KIND), IsInterfaceType< T >::value >
 
- Static Public Attributes inherited from BaseRef< T, HANDLER >
static const Bool DIRECT_REF
 
- Protected Attributes inherited from BaseRef< T, HANDLER >
T * _object
 

Member Typedef Documentation

◆ Ptr

using Ptr = StrongRef<INTERFACE>
private

Constructor & Destructor Documentation

◆ ThreadRefTemplate() [1/2]

◆ ThreadRefTemplate() [2/2]

Member Function Documentation

◆ MAXON_DEFAULT_REFERENCE_CONSTRUCTORS()

MAXON_DEFAULT_REFERENCE_CONSTRUCTORS ( ThreadRefTemplate< INTERFACE >  ,
Ptr   
)

◆ Create()

static auto Create ( FN &&  src,
ARGS &&...  args 
) -> ResultMemT<ThreadResultRef<decltype(src(std::forward<ARGS>(args)...))>>
static

Creates a reference to a thread with n arguments.

Parameters
[in]srcLambda or object with operator ().
[in]argsArguments for the function.
Template Parameters
BBehaviour for early thread cancellation.
FNType of function/lambda, deduced by the compiler.
ARGSParameter types.
Returns
OK on success.

◆ IsRunning()

Bool IsRunning ( void  ) const

Checks whether this thread is currently running. Will return false for a null reference. THREADSAFE.

Returns
False if the thread wasn't running anymore.

◆ Wait()

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

Waits until the referenced 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 or there is no job at all.

◆ GetResult()

Result<void> GetResult ( TimeValue  timeout = TIMEVALUE_INFINITE,
WAITMODE  mode = WAITMODE::DEFAULT 
) const

Waits until this thread has been executed and returns the result. 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
OK on success.

◆ Cancel()

void Cancel ( )

Asks the thread to cancel execution. The call will not wait for the thread to cancel. THREADSAFE.

◆ IsCancelled()

Bool IsCancelled ( ) const

Checks if the thread should stop. Will return true for a null reference. THREADSAFE.

Returns
True if the thread has been asked to cancel.

◆ CancelAndWait()

void CancelAndWait ( WAITMODE  mode = WAITMODE::DEFAULT)

Asks the thread to cancel execution and waits until it has finished. THREADSAFE.

Parameters
[in]modeWAITMODE::DEFAULT by default.

◆ 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. Fails if the thread is already running or no more threads are available.

◆ ObservableFinished()

ObservableFinishedBase<INTERFACE> ObservableFinished ( )

ObservableFinished is an observable that is triggered after this job has been executed. THREADSAFE.

Returns
Custom observable.

◆ GetCurrentThread()

static StrongRef<const INTERFACE> 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)

◆ GetCurrentThreadCount()

static Int GetCurrentThreadCount ( )
static

Returns the number of worker threads for the current job context. This might be different from the actual CPU core or thread count. THREADSAFE.

Returns
Number of worker threads, guaranteed to be > 0.

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

static THREADTYPE GetCurrentThreadType ( )
static

Returns information about the current thread. THREADSAFE.

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.

◆ IsCurrentThreadCancelled() [1/2]

static Bool IsCurrentThreadCancelled ( const ThreadInterface optionalThread = nullptr)
static

Checks if the currently running thread (or job) should stop. Works for jobs and threads. THREADSAFE.

Parameters
[in]optionalThreadOptional thread which should also be checked for cancellation.
Returns
True if the thread has been asked to cancel.

◆ IsCurrentThreadCancelled() [2/2]

static Bool IsCurrentThreadCancelled ( const ThreadRefTemplate< INTERFACE > &  optionalThread)
static

◆ Run() [1/2]

static MAXON_WARN_UNUSED auto Run ( FN &&  src,
THREADPRIORITY  priority = THREADPRIORITY::NORMAL 
) -> ResultMemT<ThreadResultRef<decltype(src())>>
static

Runs a lambda or object with operator () and n arguments in a thread. THREADSAFE.

Parameters
[in]srcLambda or object with operator ().
[in]priorityTHREADPRIORITY::NORMAL or THREADPRIORITY::BELOW for a background thread.
Template Parameters
BBehaviour for early thread cancellation.
FNType of function/lambda, deduced by the compiler.
Returns
The ThreadInterface encapsulating the closure, might be nullptr if starting the thread failed.

◆ Run() [2/2]

static auto Run ( FN &&  src,
THREADPRIORITY  priority,
ARGS &&...  args 
) -> ResultMemT<ThreadResultRef<decltype(src(std::forward<ARGS>(args)...))>>
static

Runs a lambda or object with operator () and n arguments in a thread. THREADSAFE.

Parameters
[in]srcLambda or object with operator ().
[in]priorityTHREADPRIORITY::NORMAL or THREADPRIORITY::BELOW for a background thread.
[in]argsArguments for the function.
Template Parameters
BBehaviour for early thread cancellation.
FNType of function/lambda, deduced by the compiler.
ARGSParameter types.
Returns
The ThreadInterface encapsulating the closure, might be nullptr if starting the thread failed.

◆ ToString()

String ToString ( const FormatStatement formatStatement) 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.

◆ operator==()

Bool operator== ( const ThreadRefTemplate< INTERFACE > &  other) const

◆ operator!=()

Bool operator!= ( const ThreadRefTemplate< INTERFACE > &  other) const

◆ NullValue()

static const ThreadRefTemplate& NullValue ( )
static

◆ GCCWorkaroundRun()

INTERFACE* GCCWorkaroundRun ( THREADPRIORITY  priority)
private

Workaround for buggy gcc 4.7. It mixes up the member method Run(priority) and the static method Run(fn, priority). THREADSAFE.

Parameters
[in]priorityTHREADPRIORITY::NORMAL or THREADPRIORITY::BELOW for a background thread.
Returns
The ThreadInterface encapsulating the closure, might be nullptr if memory allocation or thread start failed.

◆ CreateThread()

static INTERFACE* CreateThread ( FN &&  src,
ARGS &&...  args 
)
staticprivate