Threading

Detailed Description

Classes
class	ConditionVariableInterface
class	JobInterface
class	JobStatusInterface
class	JobStatusRef
class	JobResultInterface< RESULTVALUETYPE >
class	JobResultInterface< Result< RESULTVALUETYPE > >
class	JobResultInterface< Result< void > >
class	JobResultInterface< void >
class	JobResultRef< RESULTVALUETYPE >
class	JobInterfaceTemplate< IMPLEMENTATION, RESULTVALUETYPE >
struct	ResultMemJob< RESULT_TYPE >
class	JobRef
class	JobResultRef< Result< RESULTVALUETYPE > >
class	PromiseRef< RESULTVALUETYPE >
class	Promise< T >
class	JobGroupInterface
class	JobGroupRef
class	StaticJobArray< T >
class	StaticJobGroupInterface< T >
class	StaticJobGroupRef< T >
class	JobQueueInterface
class	ServiceIOJobQueueInterface
class	SerialJobQueueInterface
class	JobQueueRef
class	ServiceIOJobQueueRef
class	SerialJobQueueRef
class	LazyInit
class	LazyInitThreaded
class	ParallelFor
class	ParallelImage
struct	Spinlock
struct	RWSpinlock
class	ScopedLock
class	ScopedLockPair
class	ScopedReadLock
class	ScopedWriteLock
class	ThreadInterface
class	ThreadResultRef< RESULTVALUETYPE >
class	ThreadInterfaceTemplate< IMPLEMENTATION >
class	ThreadRefTemplate< INTERFACE >
class	ThreadResultRef< Result< RESULTVALUETYPE > >
class	LockedResourceHelper< ENTRY >
class	LockedResourceMap< HASHTYPE, ENTRY >

Macros
#define	DISABLE_IF_LOOP_TYPE_IS_INT(TYPE, ...)

Typedefs
using	Ptr = StrongRef< JobStatusInterface >
using	ValueType = RESULTVALUETYPE
using	ValueType = RESULTVALUETYPE
using	ValueType = void
using	ValueType = void
template<typename RESULTVALUETYPE >
using	FutureRef = JobResultRef< RESULTVALUETYPE >
using	ThreadRef = ThreadRefTemplate< ThreadInterface >

Enumerations
enum class	JOBGROUPFLAGS {   DEFAULT ,   ENQUEUEING_THREAD_WAITS ,   FINALIZE_ON_WAIT ,   THREAD_AFFINITY ,   NO_JOB_DESTRUCTOR }
enum class	STATICJOBGROUPFLAGS {   DEFAULT ,   WILL_RUN_FINALIZER ,   ENQUEUEING_THREAD_WAITS ,   THREAD_AFFINITY ,   NO_JOB_DESTRUCTOR }
enum class	STATICJOBARRAYFLAGS {   DEFAULT ,   INITIALIZE_LATER }
enum class	JOBQUEUETYPE {   MAINTHREAD ,   NONE ,   LOWESTPRIORITY ,   LOWPRIORITY ,   NORMALPRIORITY ,   SERVICEIO ,   THREADLESS }
enum class	JOBQUEUEMODE {   DEFAULT ,   SPIN_ON_IDLE ,   SLEEP_ON_IDLE ,   DETACH_THREADS ,   PSEUDO_THREADS }
enum class	PARALLELFORFLAGS {   INITTHREADED_FINALIZETHREADED ,   INITTHREADED_FINALIZESYNC ,   INITSYNC_FINALIZETHREADED ,   INITSYNC_FINALIZESYNC ,   NOINIT_NOFINALIZE }

Functions
template<typename FN >
auto	ExecuteOnMainThread (FN &&fn, WAITMODE waitMode=WAITMODE::DEFAULT, TimeValue wait=TIMEVALUE_INFINITE) -> decltype(fn())
JOBOPTIONFLAGS	GetJobOptions () const
const Char *	GetName () const
	JobInterface (const JobInterfaceJumpTablePOD &jmpTable)
	~JobInterface ()
	JobInterface (JobInterface &&src)
JobInterface &	operator= (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)
JobInterface *	Enqueue (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)
JobGroupInterface *	GetJobGroup () const
ObservableFinishedBase< JobInterface >	ObservableFinished ()
ObservableCancelledBase< JobInterface >	ObservableCancelled ()
Result< void >	Then (JobInterface *next, JobQueueInterface *queue=JOBQUEUE_CURRENT)
static Int	GetCurrentWorkerThreadIndex ()
static Int	GetCurrentThreadCount ()
static Bool	IsCurrentJobCancelled (const JobInterface *optionalJob=nullptr)
static JobStatusInterface *	GetCurrentJob ()
String	ToString (const FormatStatement *formatStatement=nullptr) const
	MAXON_DISALLOW_COPY_AND_ASSIGN (JobInterface)
template<typename IMPLEMENTATION >
static IMPLEMENTATION &	GetWorker (const JobInterface *job)
template<typename IMPLEMENTATION >
static void *	DestructWorker (const JobInterface *self)
template<typename IMPLEMENTATION >
static const ErrorInterface *	RunWorker (const JobInterface *job)
template<typename T >
static const JobDependencyGroupInterface *	GetWorkerDependencyGroupImpl (const JobInterface *job, std::false_type *)
template<typename T >
static const JobDependencyGroupInterface *	GetWorkerDependencyGroupImpl (const JobInterface *job, std::true_type *)
template<typename IMPLEMENTATION >
static const JobDependencyGroupInterface *	GetWorkerDependencyGroup (const JobInterface *job)
template<typename IMPLEMENTATION >
static void *	GetWorkerOptions (const JobInterface *self, Int selector, void *param)
static CoreJobGroup &	GetCoreJobGroup (JobGroupInterface *group)
Bool	IsCancelled () const
JobGroupInterface *	GetJobGroup () const
	MAXON_DEFAULT_REFERENCE_CONSTRUCTORS (JobStatusRef, Ptr)
MAXON_IMPLICIT	JobStatusRef (const Ptr &src)
MAXON_IMPLICIT	JobStatusRef (Ptr &&src)
MAXON_IMPLICIT	JobStatusRef (const JobInterface *src)
MAXON_IMPLICIT	JobStatusRef (const ThreadInterface *src)
MAXON_IMPLICIT	JobStatusRef (const StrongRef< JobInterface > &src)
MAXON_IMPLICIT	JobStatusRef (const StrongRef< ThreadInterface > &src)
Bool	IsCancelled () const
JobGroupInterface *	GetJobGroup () const
static MAXON_ATTRIBUTE_FORCE_INLINE const JobStatusRef &	NullValue ()
String	ToString (const FormatStatement *formatStatement=nullptr) const
JobStatusInterface *	operator-> () const
Result< RESULTVALUETYPE >	GetResult (TimeValue timeout=TIMEVALUE_INFINITE, WAITMODE mode=WAITMODE::DEFAULT) const
Result< RESULTVALUETYPE >	MoveResult (TimeValue timeout=TIMEVALUE_INFINITE, WAITMODE mode=WAITMODE::DEFAULT)
ResultOk< void >	SetResult (RESULTVALUETYPE &&value)
RESULTVALUETYPE &	GetResultValue ()
template<typename FN , typename... ARGS>
Result< void >	Invoke (FN &&obj, ARGS &&... args)
Result< RESULTVALUETYPE >	GetResult (TimeValue timeout=TIMEVALUE_INFINITE, WAITMODE mode=WAITMODE::DEFAULT) const
Result< RESULTVALUETYPE >	MoveResult (TimeValue timeout=TIMEVALUE_INFINITE, WAITMODE mode=WAITMODE::DEFAULT)
template<typename R >
Result< void >	SetResult (R &&value)
RESULTVALUETYPE &	GetResultValue ()
template<typename FN , typename... ARGS>
Result< void >	Invoke (FN &&obj, ARGS &&... args)
template<typename R >
Result< void >	SetResult (R &&resultOnly)
void	GetResultValue ()
template<typename FN , typename... ARGS>
Result< void >	Invoke (FN &&obj, ARGS &&... args)
ResultOk< void >	SetResult ()
void	GetResultValue ()
template<typename FN , typename... ARGS>
Result< void >	Invoke (FN &&obj, ARGS &&... args)
template<typename... ARGS>
static ResultMemT< JobResultRef< RESULTVALUETYPE > >	Create (ARGS &&... args)
	MAXON_DISALLOW_COPY_AND_ASSIGN (JobInterfaceTemplate)
	MAXON_DATATYPE (JobRef, "net.maxon.datatype.job")
enum maxon::JOBGROUPFLAGS	MAXON_ENUM_FLAGS (JOBGROUPFLAGS)
enum maxon::STATICJOBGROUPFLAGS	MAXON_ENUM_FLAGS (STATICJOBGROUPFLAGS)
enum maxon::STATICJOBARRAYFLAGS	MAXON_ENUM_FLAGS (STATICJOBARRAYFLAGS)
enum maxon::JOBQUEUETYPE	MAXON_ENUM_LIST (JOBQUEUETYPE)
enum maxon::JOBQUEUEMODE	MAXON_ENUM_LIST (JOBQUEUEMODE)
enum maxon::PARALLELFORFLAGS	MAXON_ENUM_FLAGS (PARALLELFORFLAGS)
template<typename... ARGS>
Result< void >	ParallelInvoke (Bool parallel, ARGS &&... args)
	MAXON_DATATYPE (ThreadRef, "net.maxon.datatype.threadref")

Variables
RESULTVALUETYPE	_result
RESULTVALUETYPE	_result
static const Int	JOBQUEUE_USEMAXIMUMTHREADS
static const JobQueueInterface::Current	JOBQUEUE_CURRENT
static const JobQueueInterface::None	JOBQUEUE_NONE
static const Int	PARALLELFOR_DEFAULTGRANULARITY
static const Int	PARALLELFOR_MINIMUMGRANULARITY
static const Int	PARALLELFOR_USEMAXIMUMTHREADS
static const Int	PARALLELFOR_DISABLETHREADING
static const Int	PARALLELFOR_MAXIMUMDEPTH
Bool	g_trackSpinlocks

Friends
class	StrongRefHandler
template<typename >
struct	ObservableFinishedBase
template<typename >
struct	ObservableCancelledBase
class	JobStatusInterface
class	JobGroupInterface
template<typename >
class	StaticJobGroupInterface
class	TimerInterface
class	StrongRefHandler
template<typename >
struct	MoveToTuple
template<typename , typename , typename , typename >
class	ContinuationJob
template<typename >
struct	MoveToTuple
template<typename , typename , typename , typename >
class	ContinuationJob
template<typename >
struct	MoveToTuple
template<typename , typename , typename , typename >
class	ContinuationJob
template<typename >
struct	MoveToTuple
template<typename , typename , typename , typename >
class	ContinuationJob
template<typename FN >
auto	ExecuteOnMainThread (FN &&fn, WAITMODE waitMode, TimeValue wait) -> decltype(fn())

Macro Definition Documentation

DISABLE_IF_LOOP_TYPE_IS_INT

#define DISABLE_IF_LOOP_TYPE_IS_INT	(		TYPE,
			...
	)

Typedef Documentation

Ptr

using Ptr = StrongRef<JobStatusInterface>

private

ValueType [1/4]

using ValueType = RESULTVALUETYPE

protected

ValueType [2/4]

using ValueType = RESULTVALUETYPE

protected

ValueType [3/4]

using ValueType = void

protected

ValueType [4/4]

using ValueType = void

protected

FutureRef

using FutureRef = JobResultRef<RESULTVALUETYPE>

ThreadRef

using ThreadRef = ThreadRefTemplate<ThreadInterface>

Reference to a thread (ThreadInterface).

Enumeration Type Documentation

JOBGROUPFLAGS

enum JOBGROUPFLAGS

strong

Flags for enqueue options of a JobGroup.

Enumerator
DEFAULT	Default case.
ENQUEUEING_THREAD_WAITS	The enqueuing thread waits until the group has finished and might be used to execute jobs.
FINALIZE_ON_WAIT	After Enqueue() further Add()s can be made which start the jobs ASAP. A following call to Wait() or GetResult() finalizes the group (no more jobs can be added). Can be useful if there is a lot of setup work before a job can be added.
THREAD_AFFINITY	On Enqueue() each jobs is permanently assigned to a worker thread. This blocks load balancing and is therefore slower and only useful for special cases. If a group with thread affinity had more jobs than the queue had threads its jobs must not have dependencies or wait calls. Only supported for queues where thread affinity has been enabled.
NO_JOB_DESTRUCTOR	The individual jobs do not require destruction.

STATICJOBGROUPFLAGS

enum STATICJOBGROUPFLAGS

strong

Flags describing the ownership of a StaticJobGroup. You don't have to bother using anything other than DEFAULT.

Enumerator
DEFAULT	Safe default case.
WILL_RUN_FINALIZER	A single-threaded finalizer will run after waiting for the group.
ENQUEUEING_THREAD_WAITS	The enqueuing thread waits until the group has finished and might be used to execute jobs.
THREAD_AFFINITY	On Enqueue() each jobs is permanently assigned to a worker thread. This blocks load balancing and therefore slower and only useful for special cases.
NO_JOB_DESTRUCTOR	The individual jobs do not require destruction.

STATICJOBARRAYFLAGS

enum STATICJOBARRAYFLAGS

strong

Initialization options for the StaticJobArray.

Enumerator
DEFAULT	Default behaviour: Array is empty.
INITIALIZE_LATER	Array consists of as many uninitialized elements as it has capacity. The caller will construct them later on (before it is added to the group).

JOBQUEUETYPE

enum JOBQUEUETYPE

strong

Type of job queue.

Enumerator
MAINTHREAD	Jobs are executed on the main thread whenever the event loop can spare some time: there is only one queue of this type: use GetMainThreadQueue() to access it.
NONE	Jobs are not enqueued but executed in the current context.
LOWESTPRIORITY	Use lowest priority threads (worker threads have lowest priority and will not idle when waiting for new jobs or waiting for a group to finish).
LOWPRIORITY	Use low priority threads.
NORMALPRIORITY	Use normal priority threads (You should rarely have to create a queue with normal priority. Most of the time low priority is sufficient: This makes sure that you don't interfere with really important tasks and if available you still get all cpu power).
SERVICEIO	Queue is used for IO and priority is adapted accordingly. Spinning on idle is not allowed.
THREADLESS

JOBQUEUEMODE

enum JOBQUEUEMODE

strong

Options for the job queue.

Enumerator
DEFAULT	Use default settings for the queue.
SPIN_ON_IDLE	When there are no jobs threads will be spinning for a short moment before they go to sleep (low latency and highest performance but might unnecessary steals cycles from other threads).
SLEEP_ON_IDLE	When there are no jobs threads will immediately go to sleep (results in higher latency).
DETACH_THREADS	When there are no jobs the threads will immediately go to sleep and make themselves available to other queues (results in higher latency but less memory/resource usage).
PSEUDO_THREADS	The workers behave like ordinary threads (JOBQUEUE_CURRENT points to the default queue and the threads don't have a worker thread index).

PARALLELFORFLAGS

enum PARALLELFORFLAGS

strong

Flags controlling the threading of the init and finalize section of ParallelFor. The default case is INITTHREADED_FINALIZESYNC. Each worker thread will independently call the init section for its part of the loop and then execute the loop body. The init section of a thread might be executed after any another thread has almost executed the whole loop - there's no guarantee that all init sections have finished before the loop body is entered, you might even have worker threads that don't run the init, loop and finalize section because another thread has already done the whole work. After the loop has finished for each init section the corresponding finalize will be called synchronously one after another. There might be cases where you must make sure that the init section for all worker threads has finished before the loop is executed, for example because you also must initialize some global variables for each worker thread that will be utilized by nested ParallelFors or other sub-jobs. Depending on your needs you might specify INITSYNC_FINALIZETHREADED,

Enumerator
INITTHREADED_FINALIZETHREADED	Init() and Finalize() calls are threaded.
INITTHREADED_FINALIZESYNC	Init() is called threaded, Finalize() is called synchronously (default case).
INITSYNC_FINALIZETHREADED	Init() is called synchronously, Finalize() is called threaded.
INITSYNC_FINALIZESYNC	Init() and Finalize() are called synchronously.
NOINIT_NOFINALIZE	no call to Init() or Finalize().

Function Documentation

ExecuteOnMainThread()

auto ExecuteOnMainThread	(	FN &&	fn,
		WAITMODE	waitMode,
		TimeValue	timeout
	)		-> decltype(fn())

Executes a lambda on the main thread and returns its result (if any). If the current thread is the main thread the lambda is executed directly. Otherwise a job will be enqueued and the function waits until it has finished. If the job does not return any values and can be executed asynchronously you might specify DONT_WAIT as waitMode parameter. The job is always guaranteed to be executed and this method will only return an error if the lambda does.

Parameters

[in]	fn	Lambda object with the code to be executed.
[in]	waitMode	DONT_WAIT if you don't want to wait, otherwise it defines the waitMode of the operation. Useful values are WAITMODE::RETURN_ON_CANCEL if you want to return on thrread cancelation to prevent dead locks
[in]	timeout	The time to wait for the execution (infinite by default).

Returns

Return value of the lambda.

GetJobOptions()

JOBOPTIONFLAGS GetJobOptions

(

)

const

Note

This method must not block. It can be called from any thread and this might happen concurrently.

GetName()

const Char* GetName

(

)

const

Note

This method must not block. It can be called from any thread and this might happen concurrently.

JobInterface() [1/2]

JobInterface ( const JobInterfaceJumpTablePOD &  jmpTable )

explicit

Initializes the JobInterface including the jump table to the implementation methods.

Parameters

[in]

jmpTable

Jump table of the implementation class.

~JobInterface()

~JobInterface

(

)

JobInterface() [2/2]

JobInterface

(

JobInterface &&

src

)

Move constructor is just for use with BaseArray (JobGroupInterface::Add())

operator=()

JobInterface& operator=

(

JobInterface &&

src

)

Move assignment operator is just for use with BaseArray (JobGroupInterface::Add()).

Wait()

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

Waits until this 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() [1/3]

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.

MoveResult() [1/3]

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

Waits until this job has been executed and returns the result via std::move.

Note

You may only use MoveResult() if you can ensure that nobody else will ask for the result of the job. 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() [1/3]

Bool IsCancelled

(

)

const

Checks if the job should stop. 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()

JobInterface* Enqueue

(

JobQueueInterface *

queue = JOBQUEUE_CURRENT

)

Enqueues this job (will add a reference and remove it when the object is no longer needed). THREADSAFE.

Parameters

[in]

queue

The queue, use JOBQUEUE_CURRENT for the current queue.

Returns

Always this pointer (for concatenation).

AddSubJob() [1/3]

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.

AddSubJob() [2/3]

Result<void> AddSubJob

(

ResultMemT< JOB * >

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.

AddSubJob() [3/3]

Result<void> AddSubJob

(

ResultMemT< JOBREF > &&

subJob

)

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

Parameters

[in]

subJob

Job (encapsulated in a ResultMemT directly returned from creation).

Returns

OK on success.

AddSubGroup() [1/3]

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.

AddSubGroup() [2/3]

Result<void> AddSubGroup

(

ResultMemT< GROUP * >

subGroup

)

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

Parameters

[in]

subGroup

Job group (encapsulated in a ResultMemT directly returned from creation).

Returns

OK on success.

AddSubGroup() [3/3]

Result<void> AddSubGroup

(

ResultMemT< GROUP >

subGroup

)

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

Parameters

[in]

subGroup

Job group (encapsulated in a ResultMemT directly returned from creation).

Returns

OK on success.

GetJobGroup() [1/3]

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.

Then()

Result<void> Then	(	JobInterface *	next,
		JobQueueInterface *	queue = JOBQUEUE_CURRENT
	)

Adds an observer which is enqueued when this job has been executed. THREADSAFE.

Returns

OK on success.

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

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.

GetCurrentJob()

static JobStatusInterface* GetCurrentJob ( )

static

Returns a pointer to the currently running job which can be used to check if it's cancelled. Works for jobs and threads.

Returns

Currently running job. Can be nullptr if called from an alien thread.

ToString() [1/2]

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.

MAXON_DISALLOW_COPY_AND_ASSIGN() [1/2]

MAXON_DISALLOW_COPY_AND_ASSIGN ( JobInterface  )

private

GetWorker()

static IMPLEMENTATION& GetWorker ( const JobInterface *  job )

staticprivate

DestructWorker()

static void* DestructWorker ( const JobInterface *  self )

staticprivate

RunWorker()

static const ErrorInterface* RunWorker ( const JobInterface *  job )

staticprivate

GetWorkerDependencyGroupImpl() [1/2]

static const JobDependencyGroupInterface* GetWorkerDependencyGroupImpl ( const JobInterface *  job, std::false_type *    )

staticprivate

GetWorkerDependencyGroupImpl() [2/2]

static const JobDependencyGroupInterface* GetWorkerDependencyGroupImpl ( const JobInterface *  job, std::true_type *    )

staticprivate

GetWorkerDependencyGroup()

static const JobDependencyGroupInterface* GetWorkerDependencyGroup ( const JobInterface *  job )

staticprivate

GetWorkerOptions()

static void* GetWorkerOptions ( const JobInterface *  self, Int  selector, void *  param  )

staticprivate

GetCoreJobGroup()

static CoreJobGroup& GetCoreJobGroup ( JobGroupInterface *  group )

staticprivate

IsCancelled() [2/3]

Bool IsCancelled

(

)

const

Checks if the job should stop. THREADSAFE.

Returns

True if the job has been asked to cancel.

GetJobGroup() [2/3]

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.

MAXON_DEFAULT_REFERENCE_CONSTRUCTORS()

MAXON_DEFAULT_REFERENCE_CONSTRUCTORS	(	JobStatusRef	,
		Ptr
	)

JobStatusRef() [1/6]

MAXON_IMPLICIT JobStatusRef

(

const Ptr &

src

)

JobStatusRef() [2/6]

MAXON_IMPLICIT JobStatusRef

(

Ptr &&

src

)

JobStatusRef() [3/6]

MAXON_IMPLICIT JobStatusRef

(

const JobInterface *

src

)

JobStatusRef() [4/6]

MAXON_IMPLICIT JobStatusRef

(

const ThreadInterface *

src

)

JobStatusRef() [5/6]

MAXON_IMPLICIT JobStatusRef

(

const StrongRef< JobInterface > &

src

)

JobStatusRef() [6/6]

MAXON_IMPLICIT JobStatusRef

(

const StrongRef< ThreadInterface > &

src

)

IsCancelled() [3/3]

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.

GetJobGroup() [3/3]

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.

NullValue()

static MAXON_ATTRIBUTE_FORCE_INLINE const JobStatusRef& NullValue ( )

static

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

Returns

A null value of the JobRef.

ToString() [2/2]

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

JobStatusInterface* operator-> ( void  ) const

protected

GetResult() [2/3]

Result<RESULTVALUETYPE> 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

Result value on success.

MoveResult() [2/3]

Result<RESULTVALUETYPE> MoveResult	(	TimeValue	timeout = TIMEVALUE_INFINITE,
		WAITMODE	mode = WAITMODE::DEFAULT
	)

Waits until this job has been executed and returns the result via std::move.

Note

You may only use MoveResult() if you can ensure that nobody else will ask for the result of the job. 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

Result value on success.

SetResult() [1/4]

ResultOk<void> SetResult ( RESULTVALUETYPE &&  value )

protected

Sets the result value returned by GetResult().

Returns

OK on success.

GetResultValue() [1/4]

RESULTVALUETYPE& GetResultValue ( )

protected

Invoke() [1/4]

Result<void> Invoke ( FN &&  obj, ARGS &&...  args  )

protected

GetResult() [3/3]

Result<RESULTVALUETYPE> 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

Result value on success.

MoveResult() [3/3]

Result<RESULTVALUETYPE> MoveResult	(	TimeValue	timeout = TIMEVALUE_INFINITE,
		WAITMODE	mode = WAITMODE::DEFAULT
	)

Waits until this job has been executed and returns the result via std::move.

Note

You may only use MoveResult() if you can ensure that nobody else will ask for the result of the job. 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

Result value on success.

SetResult() [2/4]

Result<void> SetResult ( R &&  value )

protected

Sets the result value returned by GetResult().

Returns

OK on success.

GetResultValue() [2/4]

RESULTVALUETYPE& GetResultValue ( )

protected

Invoke() [2/4]

Result<void> Invoke ( FN &&  obj, ARGS &&...  args  )

protected

SetResult() [3/4]

Result<void> SetResult ( R &&  resultOnly )

protected

Sets the result value returned by GetResult() (in this specialisation the Result<void> is just forwarded).

Returns

OK on success.

GetResultValue() [3/4]

void GetResultValue ( )

protected

Invoke() [3/4]

Result<void> Invoke ( FN &&  obj, ARGS &&...  args  )

protected

SetResult() [4/4]

ResultOk<void> SetResult ( )

protected

Sets the result value returned by GetResult() (in this specialisiation just a dummy because it's void).

Returns

OK on success.

GetResultValue() [4/4]

void GetResultValue ( )

protected

Invoke() [4/4]

Result<void> Invoke ( FN &&  obj, ARGS &&...  args  )

protected

Create()

static ResultMemT<JobResultRef<RESULTVALUETYPE> > Create ( ARGS &&...  args )

static

Creates the job.

Parameters

[in]

args

Arguments for the construcor.

Template Parameters

ARGS	Parameter types.

Returns

JobRef on success, OutOfMemoryerror on failure.

MAXON_DISALLOW_COPY_AND_ASSIGN() [2/2]

MAXON_DISALLOW_COPY_AND_ASSIGN ( JobInterfaceTemplate< IMPLEMENTATION, RESULTVALUETYPE >  )

private

MAXON_DATATYPE() [1/2]

maxon::MAXON_DATATYPE	(	JobRef	,
		"net.maxon.datatype.job"
	)

MAXON_ENUM_FLAGS() [1/4]

enum maxon::JOBGROUPFLAGS maxon::MAXON_ENUM_FLAGS

(

JOBGROUPFLAGS

)

MAXON_ENUM_FLAGS() [2/4]

enum maxon::STATICJOBGROUPFLAGS maxon::MAXON_ENUM_FLAGS

(

STATICJOBGROUPFLAGS

)

MAXON_ENUM_FLAGS() [3/4]

enum maxon::STATICJOBARRAYFLAGS maxon::MAXON_ENUM_FLAGS

(

STATICJOBARRAYFLAGS

)

MAXON_ENUM_LIST() [1/2]

enum maxon::JOBQUEUETYPE maxon::MAXON_ENUM_LIST

(

JOBQUEUETYPE

)

MAXON_ENUM_LIST() [2/2]

enum maxon::JOBQUEUEMODE maxon::MAXON_ENUM_LIST

(

JOBQUEUEMODE

)

MAXON_ENUM_FLAGS() [4/4]

enum maxon::PARALLELFORFLAGS maxon::MAXON_ENUM_FLAGS

(

PARALLELFORFLAGS

)

ParallelInvoke()

Result<void> maxon::ParallelInvoke	(	Bool	parallel,
		ARGS &&...	args
	)

Executes multiple functions in parallel and waits until they have finished. The parallel flag should be used for recursive code and set to false once the work item size is so small it wouldn't make sense to parallelize it any further. Please note that using ParallelInvoke() to parallelize a recursive algorithm is handy but will never perform as good as using a parallelized non-recursive algorithm because of the required synchronization at each recursion level. Execution of the parallel code is guaranteed - even under low memory conditions. If the lambdas do not return Result<void> the routine will return OK.

Parameters

[in]	parallel	True for parallel execution, false if amount of work has become very small.
[in]	args	Callable objects, usually lambdas.

Template Parameters

ARGS	Parameter types.

Returns

OK on success. Will only return an error if a lambda returns one via Result<void>. Please note that you'll receive an AggregatedError here that contains the errors created in the lambda and not the errors directly.

MAXON_DATATYPE() [2/2]

maxon::MAXON_DATATYPE	(	ThreadRef	,
		"net.maxon.datatype.threadref"
	)

Variable Documentation

_result [1/2]

RESULTVALUETYPE _result

private

_result [2/2]

RESULTVALUETYPE _result

private

JOBQUEUE_USEMAXIMUMTHREADS

const Int JOBQUEUE_USEMAXIMUMTHREADS

static

JOBQUEUE_CURRENT

const JobQueueInterface::Current JOBQUEUE_CURRENT

static

Equivalent to calling GetDestinationQueue(), you just save a function call.

JOBQUEUE_NONE

const JobQueueInterface::None JOBQUEUE_NONE

static

For notifications and timer jobs: Executes them immediately on the current thread.

PARALLELFOR_DEFAULTGRANULARITY

const Int PARALLELFOR_DEFAULTGRANULARITY

static

PARALLELFOR_MINIMUMGRANULARITY

const Int PARALLELFOR_MINIMUMGRANULARITY

static

PARALLELFOR_USEMAXIMUMTHREADS

const Int PARALLELFOR_USEMAXIMUMTHREADS

static

PARALLELFOR_DISABLETHREADING

const Int PARALLELFOR_DISABLETHREADING

static

PARALLELFOR_MAXIMUMDEPTH

const Int PARALLELFOR_MAXIMUMDEPTH

static

g_trackSpinlocks

Bool g_trackSpinlocks

extern

Friends

StrongRefHandler [1/2]

friend class StrongRefHandler

friend

ObservableFinishedBase

friend struct ObservableFinishedBase

friend

ObservableCancelledBase

friend struct ObservableCancelledBase

friend

JobStatusInterface

friend class JobStatusInterface

friend

JobGroupInterface

friend class JobGroupInterface

friend

StaticJobGroupInterface

friend class StaticJobGroupInterface

friend

TimerInterface

friend class TimerInterface

friend

StrongRefHandler [2/2]

friend class StrongRefHandler

friend

MoveToTuple [1/4]

friend struct MoveToTuple

friend

ContinuationJob [1/4]

friend class ContinuationJob

friend

MoveToTuple [2/4]

friend struct MoveToTuple

friend

ContinuationJob [2/4]

friend class ContinuationJob

friend

MoveToTuple [3/4]

friend struct MoveToTuple

friend

ContinuationJob [3/4]

friend class ContinuationJob

friend

MoveToTuple [4/4]

friend struct MoveToTuple

friend

ContinuationJob [4/4]

friend class ContinuationJob

friend

ExecuteOnMainThread

auto ExecuteOnMainThread ( FN &&  fn, WAITMODE  waitMode, TimeValue  wait  ) -> decltype(fn())

friend

Executes a lambda on the main thread and returns its result (if any). If the current thread is the main thread the lambda is executed directly. Otherwise a job will be enqueued and the function waits until it has finished. If the job does not return any values and can be executed asynchronously you might specify DONT_WAIT as waitMode parameter. The job is always guaranteed to be executed and this method will only return an error if the lambda does.

Parameters

[in]	fn	Lambda object with the code to be executed.
[in]	waitMode	DONT_WAIT if you don't want to wait, otherwise it defines the waitMode of the operation. Useful values are WAITMODE::RETURN_ON_CANCEL if you want to return on thrread cancelation to prevent dead locks
[in]	timeout	The time to wait for the execution (infinite by default).

Returns

Return value of the lambda.