JobRef Class Reference

#include <job.h>

Inheritance diagram for JobRef:

Detailed Description

Reference to a job (JobInterface).

Public Member Functions

 MAXON_DEFAULT_REFERENCE_CONSTRUCTORS (JobRef, Ptr)
 
MAXON_IMPLICIT JobRef (const Ptr &src)
 
MAXON_IMPLICIT JobRef (Ptr &&src)
 
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)
 
JobRefEnqueue (JobQueueInterface *queue=JOBQUEUE_CURRENT)
 
Result< void > AddSubJob (JobInterface *subJob)
 
template<JOBCANCELLATION B = JOBCANCELLATION::ISOK, typename FN >
 DISABLE_IF_JOBREF (FN, Result< void >) AddSubJob(FN &&src)
 
template<typename GROUP >
Result< void > AddSubGroup (GROUP *subGroup)
 
JobGroupInterfaceGetJobGroup () const
 
ObservableFinishedBase< JobInterfaceObservableFinished ()
 
ObservableCancelledBase< JobInterfaceObservableCancelled ()
 
String ToString (const FormatStatement *formatStatement) 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)
 
T & GetOrNull () const
 
 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_REPLACEMENT(base_of, BaseRef, REF) && maxon::HasErasedBase<typename REF::ReferencedType, ReferencedType>::value>::type>
MAXON_IMPLICIT BaseRef (const REF &src)
 
template<typename REF , typename = typename std::enable_if<!STD_IS_REPLACEMENT(base_of, BaseRef, REF) && maxon::HasErasedBase<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_REPLACEMENT(base_of, BaseRef, REF) && maxon::HasErasedBase<typename REF::ReferencedType, ReferencedType>::value>::type>
BaseRefoperator= (const REF &src)
 
template<typename REF , typename = typename std::enable_if<!STD_IS_REPLACEMENT(base_of, BaseRef, REF) && maxon::HasErasedBase<typename REF::ReferencedType, ReferencedType>::value>::type>
BaseRefoperator= (REF &src)
 
 BaseRef (BaseRef &&src)
 
template<typename REF , typename = typename std::enable_if<!STD_IS_REPLACEMENT(const, REF) && !STD_IS_REPLACEMENT(base_of, BaseRef, REF) && maxon::HasErasedBase<typename REF::ReferencedType, ReferencedType>::value>::type>
MAXON_IMPLICIT BaseRef (REF &&src)
 
BaseRefoperator= (BaseRef &&src)
 
template<typename REF , typename = typename std::enable_if<!STD_IS_REPLACEMENT(const, REF) && !STD_IS_REPLACEMENT(base_of, BaseRef, REF) && maxon::HasErasedBase<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)
 
void PrivateSetPointer (T *ptr)
 

Static Public Member Functions

template<JOBCANCELLATION B = JOBCANCELLATION::AUTOMATIC, typename FN , typename... ARGS>
static auto Create (FN &&src, ARGS &&... args) -> ResultMemT< JobResultRef< decltype(src(std::forward< ARGS >(args)...))>>
 
template<JOBCANCELLATION B = JOBCANCELLATION::AUTOMATIC, typename FN >
static MAXON_WARN_UNUSED auto Enqueue (FN &&src, JobQueueInterface *queue=JOBQUEUE_CURRENT) -> ResultMemT< JobResultRef< decltype(src())>>
 
template<JOBCANCELLATION B = JOBCANCELLATION::AUTOMATIC, typename FN , typename... ARGS>
static MAXON_WARN_UNUSED auto Enqueue (FN &&src, JobQueueInterface *queue, ARGS &&... args) -> ResultMemT< JobResultRef< decltype(src(std::forward< ARGS >(args)...))>>
 
static Int GetCurrentWorkerThreadIndex ()
 
static Int GetCurrentThreadCount ()
 
static Bool IsCurrentJobCancelled (const JobInterface *optionalJob=nullptr)
 
static Bool IsCurrentJobCancelled (const JobRef &optionalJob)
 
static JobStatusInterfaceGetCurrentJob ()
 
static const JobRefNullValue ()
 
- Static Public Member Functions inherited from BaseRef< T, HANDLER >
static std::false_type GenericVarianceCheck (const void *)
 
template<typename... ARGS>
static MAXON_ATTRIBUTE_FORCE_INLINE ResultMemT< BaseRefCreate (ARGS &&... args)
 
static const BaseRefNullValue ()
 

Protected Member Functions

JobInterfaceoperator-> () const
 

Private Types

using Ptr = StrongRef< JobInterface >
 

Static Private Member Functions

template<JOBCANCELLATION B, typename FN , typename... ARGS>
static ResultPtr< JobInterfaceCreateJob (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 >
 
template<typename D >
using IsGenericBaseOf = std::true_type
 
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<JobInterface>
private

Constructor & Destructor Documentation

◆ JobRef() [1/2]

MAXON_IMPLICIT JobRef ( const Ptr src)

◆ JobRef() [2/2]

MAXON_IMPLICIT JobRef ( Ptr &&  src)

Member Function Documentation

◆ MAXON_DEFAULT_REFERENCE_CONSTRUCTORS()

MAXON_DEFAULT_REFERENCE_CONSTRUCTORS ( JobRef  ,
Ptr   
)

◆ Create()

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

Creates a reference to a job with n arguments.

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

◆ Wait()

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

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

Wait() might execute other jobs in the current queue until the one you are waiting for has finished or is timed out. Therefore you must 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 enqueued what you are waiting for. Otherwise Wait() will immediately return false because this would lead to a deadlock. The same applies if a job tries to wait for itself.

Instead of waiting for a job 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 job 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.

◆ GetResult()

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

Waits until this job 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 job to cancel execution. If the job is a part of a group the whole group will be cancelled. Cancellation of a job does not affect its finish observers. The call will not wait for the job to cancel. THREADSAFE.

◆ IsCancelled()

Bool IsCancelled ( ) const

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

Returns
True if the job has been asked to cancel.

◆ CancelAndWait()

void CancelAndWait ( WAITMODE  mode = WAITMODE::DEFAULT)

Asks the job to cancel execution and waits until it has finished. If the job is a part of a group the whole group will be cancelled. Cancellation of a job does not affect its finish observers. THREADSAFE.

Parameters
[in]modeWAITMODE::DEFAULT by default.

◆ Enqueue() [1/3]

JobRef& Enqueue ( JobQueueInterface queue = JOBQUEUE_CURRENT)

Enqueues the job the ref points to. THREADSAFE.

Parameters
[in]queueThe queue the object should run on (JOBQUEUE_CURRENT for current queue).
Returns
Always reference to itself (for concatenation).

◆ Enqueue() [2/3]

static MAXON_WARN_UNUSED auto Enqueue ( FN &&  src,
JobQueueInterface queue = JOBQUEUE_CURRENT 
) -> ResultMemT<JobResultRef<decltype(src())>>
static

Enqueues a lambda or object with operator (). THREADSAFE.

Parameters
[in]srcLambda or object with operator ().
[in]queueThe queue the object should run on (JOBQUEUE_CURRENT for current queue).
Template Parameters
BBehaviour for early job cancellation.
FNType of function/lambda, deduced by the compiler.
Returns
JobRef with GetResult() template for the type returned by the lambda.

◆ Enqueue() [3/3]

static MAXON_WARN_UNUSED auto Enqueue ( FN &&  src,
JobQueueInterface queue,
ARGS &&...  args 
) -> ResultMemT<JobResultRef<decltype(src(std::forward<ARGS>(args)...))>>
static

Enqueues a lambda or object with operator () and n arguments. THREADSAFE.

Parameters
[in]srcLambda or object with operator ().
[in]queueThe queue the object should run on (JOBQUEUE_CURRENT for current queue).
[in]argsArgument(s) for the function.
Template Parameters
BBehaviour for early job cancellation.
FNType of function/lambda, deduced by the compiler.
ARGSParameter types.
Returns
JobRef with GetResult() template for the type returned by the lambda.

◆ AddSubJob()

Result<void> AddSubJob ( JobInterface subJob)

Adds a job to this job's group (see JobGroup). The caller must belong to a group. THREADSAFE.

Parameters
[in]subJobJob (nullptr will return error).
Returns
OK on success.

◆ DISABLE_IF_JOBREF()

DISABLE_IF_JOBREF ( FN  ,
Result< void >   
) &&

Adds a job to this job's group (see JobGroup). The caller must belong to a group. THREADSAFE.

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

◆ AddSubGroup()

Result<void> AddSubGroup ( GROUP *  subGroup)

Adds a subgroup to this job's group. The caller must belong to a group. THREADSAFE.

Parameters
[in]subGroupJob group (nullptr will return error).
Returns
OK on success.

◆ GetJobGroup()

JobGroupInterface* GetJobGroup ( ) const

Returns the group a job belongs to. THREADSAFE.

Returns
JobGroup this job belongs to or nullptr if it's not part of a group.

◆ ObservableFinished()

ObservableFinishedBase<JobInterface> ObservableFinished ( )

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

Returns
Custom observable.

◆ ObservableCancelled()

ObservableCancelledBase<JobInterface> ObservableCancelled ( )

ObservableCancelled is an observable that is triggered when this job is cancelled. THREADSAFE.

Returns
Custom observable.

◆ GetCurrentWorkerThreadIndex()

static Int GetCurrentWorkerThreadIndex ( )
static

Returns the index of the internal worker thread which is running this job. If the job is not running as part of a worker thread 0 is returned to make sure you can safely use this as index to an array with thread local data. THREADSAFE.

Returns
Index between 0 and the number of threads used for the queue - 1.

◆ 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.

◆ IsCurrentJobCancelled() [1/2]

static Bool IsCurrentJobCancelled ( const JobInterface optionalJob = nullptr)
static

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

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

◆ IsCurrentJobCancelled() [2/2]

static Bool IsCurrentJobCancelled ( const JobRef optionalJob)
static

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

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

◆ GetCurrentJob()

static JobStatusInterface* GetCurrentJob ( )
static

Private. THREADSAFE.

Returns
Currently running internal job.

◆ NullValue()

static const JobRef& NullValue ( )
static

Returns a null value of the JobRef (see nullvalue.h for more details).

Returns
A null value of the JobRef.

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

JobInterface* operator-> ( ) const
protected

◆ CreateJob()

static ResultPtr<JobInterface> CreateJob ( FN &&  src,
ARGS &&...  args 
)
staticprivate