#include <job.h>

Inheritance diagram for JobRef:

[legend]

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)

JobRef &	Enqueue (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)

JobGroupInterface *	GetJobGroup () const

ObservableFinishedBase< JobInterface >	ObservableFinished ()

ObservableCancelledBase< JobInterface >	ObservableCancelled ()

String	ToString (const FormatStatement *formatStatement=nullptr) const

Public Member Functions inherited from BaseRef< T, HANDLER >
T *	GetPointer ()

ConstReferencedType *	GetPointer () const

T *	operator-> ()

ConstReferencedType *	operator-> () const

std::conditional< std::is_void< T >::value, DeleteReturnType01, T >::type &	operator* ()

std::conditional< std::is_void< ConstReferencedType >::value, DeleteReturnType01, T >::type &	operator* () const

	operator T* ()

	operator ConstReferencedType * () const

	operator Bool () const

	operator Bool ()

const std::conditional< std::is_void< T >::value, DeleteReturnType01, T >::type &	operator[] (Int) const =delete

ResultRef< typename std::remove_const< T >::type >	MakeWritable (Bool resetOnError=true)

ResultRef< typename std::remove_const< T >::type >	MakeWritableDontCopy ()

Bool	HasMultipleReferences () const

std::conditional< std::is_void< T >::value, DeleteReturnType01, T >::type &	GetOrDefault () 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)

BaseRef &	operator= (T *src)

BaseRef &	operator= (std::nullptr_t src)

BaseRef &	operator= (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>
BaseRef &	operator= (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>
BaseRef &	operator= (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)

BaseRef &	operator= (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>
BaseRef &	operator= (REF &&src)

	~BaseRef ()

Bool	operator== (const BaseRef &b) const

Bool	operator!= (const BaseRef &b) const

Bool	operator< (const BaseRef &b) const

	MAXON_OPERATOR_INEQUALITY (BaseRef)

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

HashInt	GetHashCode () const

UniqueHash	GetUniqueHashCode () const

std::conditional< Bool(HANDLER::KIND &VALUEKIND::COW_MASK), typename std::remove_const< T >::type, T >::type *	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 , typename DEPENDENCY , typename... ARGS>
static auto	CreateWithDependency (DEPENDENCY &&dependency, 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) -> ResultMemJob< 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)...))>>

template<JOBCANCELLATION B = JOBCANCELLATION::AUTOMATIC, typename FN >
static auto	EnqueueAndWait (FN &&src, JobQueueInterface *queue=JOBQUEUE_CURRENT) -> Result< decltype(src())>

template<JOBCANCELLATION B = JOBCANCELLATION::AUTOMATIC, typename FN , typename... ARGS>
static auto	EnqueueAndWait (FN &&src, JobQueueInterface *queue, ARGS &&... args) -> Result< 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 JobStatusInterface *	GetCurrentJob ()

static MAXON_ATTRIBUTE_FORCE_INLINE const JobRef &	DefaultValue ()

Static Public Member Functions inherited from BaseRef< T, HANDLER >
static void	PrivateLookupFn ()

static std::false_type	GenericVarianceCheck (const void *)

template<typename... ARGS>
static MAXON_ATTRIBUTE_FORCE_INLINE ResultMemT< BaseRef >	Create (ARGS &&... args)

static const BaseRef &	DefaultValueRef ()

static std::conditional< Bool(HANDLER::KIND &VALUEKIND::UNIQUE_REFERENCE), BaseRef, const BaseRef & >::type	DefaultValue ()

Protected Member Functions
JobInterface *	operator-> () const

Private Types
using	Ptr = StrongRef< JobInterface >

Static Private Member Functions
template<JOBCANCELLATION B, typename FN , typename... ARGS>
static ResultPtr< JobInterface >	CreateJob (FN &&src, ARGS &&... args)

template<JOBCANCELLATION B, typename FN , typename DEPENDENCY , typename... ARGS>
static ResultPtr< JobInterface >	CreateJobWithDependency (DEPENDENCY &&dependency, FN &&src, ARGS &&... args)

template<JOBCANCELLATION B, typename FN , typename... ARGS>
static ResultPtr< JobInterface >	CreateJobWithDependency (std::nullptr_t, 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 constexpr Bool	DIRECT_REF

Protected Attributes inherited from BaseRef< T, HANDLER >
union {
T * _object

const void * _impl

};

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]	src	Lambda or object with operator ().
[in]	args	Arguments for the function.

Template Parameters

B	Behaviour for early job cancellation.
FN	Type of function/lambda, deduced by the compiler.
ARGS	Parameter types.

Returns: OK on success.

◆ CreateWithDependency()

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

static

Creates a reference to a job with n arguments which has a dependency.

Parameters

[in]	dependency	Pointer to a dependency (can be any object, memory block, etc.). Passing a nullptr indicates an independent job (which might even be executed recursively).
[in]	src	Lambda or object with operator ().
[in]	args	Arguments for the function.

Template Parameters

B	Behaviour for early job cancellation.
FN	Type of function/lambda, deduced by the compiler.
DEPENDENCY	Type of dependency, deduced by the compiler.
ARGS	Parameter 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]	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.

◆ 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]	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: 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. A null reference will not be regarded as being cancelled. 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] mode WAITMODE::DEFAULT by default.

◆ Enqueue() [1/3]

JobRef& Enqueue ( JobQueueInterface * queue = JOBQUEUE_CURRENT )

Enqueues the job the ref points to. THREADSAFE.

Parameters

[in] queue The 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`
	)		-> ResultMemJob<decltype(src())>

static

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

Parameters

[in]	src	Lambda or object with operator ().
[in]	queue	The queue the object should run on (JOBQUEUE_CURRENT for current queue).

Template Parameters

B	Behaviour for early job cancellation.
FN	Type 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]	src	Lambda or object with operator ().
[in]	queue	The queue the object should run on (JOBQUEUE_CURRENT for current queue).
[in]	args	Argument(s) for the function.

Template Parameters

B	Behaviour for early job cancellation.
FN	Type of function/lambda, deduced by the compiler.
ARGS	Parameter types.

Returns: JobRef with GetResult() template for the type returned by the lambda.

◆ EnqueueAndWait() [1/2]

static auto EnqueueAndWait	(	FN &&	src,
		JobQueueInterface *	queue = `JOBQUEUE_CURRENT`
	)		-> Result<decltype(src())>

static

Enqueues a lambda or object with operator () and waits until the job has finished. THREADSAFE.

Parameters

[in]	src	Lambda or object with operator ().
[in]	queue	The queue the object should run on (JOBQUEUE_CURRENT for current queue).

Template Parameters

B	Behaviour for early job cancellation.
FN	Type of function/lambda, deduced by the compiler.

Returns: JobRef with GetResult() template for the type returned by the lambda.

◆ EnqueueAndWait() [2/2]

static auto EnqueueAndWait	(	FN &&	src,
		JobQueueInterface *	queue,
		ARGS &&...	args
	)		-> Result<decltype(src(std::forward<ARGS>(args)...))>

static

Enqueues a lambda or object with operator () and n arguments and waits until the job has finished. THREADSAFE.

Parameters

[in]	src	Lambda or object with operator ().
[in]	queue	The queue the object should run on (JOBQUEUE_CURRENT for current queue).
[in]	args	Argument(s) for the function.

Template Parameters

B	Behaviour for early job cancellation.
FN	Type of function/lambda, deduced by the compiler.
ARGS	Parameter 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] subJob Job (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] src Lambda or object with operator ().

Template Parameters

B	Behaviour for early job cancellation.
FN	Type 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] subGroup Job 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] optionalJob Optional 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] optionalJob Optional 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.

◆ DefaultValue()

static MAXON_ATTRIBUTE_FORCE_INLINE const JobRef& DefaultValue ( )

static

Returns a default value of the JobRef (see defaultvalue.h for more details).

Returns: A default value of the JobRef.

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

◆ operator->()

JobInterface* operator-> ( ) const

protected

◆ CreateJob()

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

staticprivate

◆ CreateJobWithDependency() [1/2]

static ResultPtr<JobInterface> CreateJobWithDependency	(	DEPENDENCY &&	dependency,
		FN &&	src,
		ARGS &&...	args
	)

staticprivate

◆ CreateJobWithDependency() [2/2]

static ResultPtr<JobInterface> CreateJobWithDependency	(	std::nullptr_t	,
		FN &&	src,
		ARGS &&...	args
	)

staticprivate

Detailed Description

Public Member Functions

Static Public Member Functions

Protected Member Functions

Private Types

Static Private Member Functions

Additional Inherited Members

Member Typedef Documentation

◆ Ptr

Constructor & Destructor Documentation

◆ JobRef() [1/2]

◆ JobRef() [2/2]

Member Function Documentation

◆ MAXON_DEFAULT_REFERENCE_CONSTRUCTORS()

◆ Create()

◆ CreateWithDependency()

◆ Wait()

◆ GetResult()

◆ Cancel()

◆ IsCancelled()

◆ CancelAndWait()

◆ Enqueue() [1/3]

◆ Enqueue() [2/3]

◆ Enqueue() [3/3]

◆ EnqueueAndWait() [1/2]

◆ EnqueueAndWait() [2/2]

◆ AddSubJob()

◆ DISABLE_IF_JOBREF()

◆ AddSubGroup()

◆ GetJobGroup()

◆ ObservableFinished()

◆ ObservableCancelled()

◆ GetCurrentWorkerThreadIndex()

◆ GetCurrentThreadCount()

◆ IsCurrentJobCancelled() [1/2]

◆ IsCurrentJobCancelled() [2/2]

◆ GetCurrentJob()

◆ DefaultValue()

◆ ToString()

◆ operator->()

◆ CreateJob()

◆ CreateJobWithDependency() [1/2]

◆ CreateJobWithDependency() [2/2]