作业手册

内容表

关于
Job
Job Group
Queue
延伸阅读

关于

A job is a threaded, reusable, independent work item (task). It can be queued to be executed with other jobs in a (parallel) pipeline.

Job

A custom job is based on maxon::JobInterfaceTemplate , maxon::JobResultInterface and maxon::JobInterface . The custom class contains data and implements the function call operator with the actual workload. A job instance is based on maxon::JobRef .

警告: Make sure that a job has no additional, hidden dependencies like for example executing parallelized code internally.

// This example shows a job that returns a value.

// FactorialJob calculates the factorial of the given number. class FactorialJob : public maxon::JobInterfaceTemplate <FactorialJob, maxon::UInt> { public : FactorialJob() { }; MAXON_IMPLICIT FactorialJob( maxon::UInt n) { _n = n; }

// function operator with the actual workload maxon::Result<void> operator ()() { // 0! and 1! are 1 maxon::UInt factorial = 1;

if ( MAXON_LIKELY (_n > 1)) { factorial = _n; while (_n > 1) { --_n; factorial *= _n; } }

// store result return SetResult (std::move(factorial)); }

private : maxon::UInt _n = 0; };

A job can also implement:

maxon::JobInterface::GetName() : Returns the name of the job.
maxon::JobInterface::GetJobOptions() : Returns the settings of the job. See maxon::JOBOPTIONFLAGS.

A job has to be enqueued in a queue to be executed (see job queue below):

maxon::JobRef::Enqueue() : Enqueues the job in the defined queue.
maxon::JobRef::Wait() : Waits until the job has finished.
maxon::JobInterface::GetResult() : Waits until the job has finished and returns the result.
maxon::JobInterface::MoveResult() : Waits until the job has finished and returns the result using std::move().

// This example creates and starts a job that will return a result value.

// create and start job const maxon::UInt n = 10; auto job = FactorialJob::Create(n) iferr_return ; job.Enqueue(); // enqueue the job in the current queue and start

// wait and get result const maxon::UInt factorial = job.GetResult() iferr_return ; DiagnosticOutput ( "@! = @" , n, factorial);

A running job can be cancelled:

maxon::JobRef::IsCancelled() : Returns true if the job should stop.
maxon::JobRef::Cancel() : Asks the job to cancel execution.
maxon::JobRef::CancelAndWait() : Asks the job to cancel execution and waits until it has ended.

// This example cancels the given job and waits for it to finish.

// cancel the given job job.CancelAndWait();

These observers can be used to react to certain events:

maxon::JobRef::ObservableFinished() : Returns the observable that is triggered after this job has been executed.
maxon::JobRef::ObservableCancelled() : Returns the observable that is triggered when the job has been cancelled.

Further utility function are:

maxon::JobInterface::ToString() : Returns a readable string of the job.

Static utility functions are:

maxon::JobInterface::GetCurrentWorkerThreadIndex() : Returns the index of the internal worker thread which is running this job. This index should not be used for calculations (e.g. used as a seed).
maxon::JobInterface::GetCurrentThreadCount() : Returns the number of worker threads for the current job context.
maxon::JobInterface::IsCurrentJobCancelled() : Returns true if the currently running job (or thread) should stop.

Job Group

Jobs can be organized in job groups. These groups are used to execute and wait for multiple jobs simultaneously. The jobs of a group typically belong together. The jobs are executed as efficiently as possible.

maxon::JobGroupRef : A simple job group.
maxon::StaticJobGroupRef : A job group with static maximum job count.

The maxon::JobGroupRef members are:

maxon::JobGroupRef::Add() : Adds a job or jobs to the group.
maxon::JobGroupRef::Enqueue() : Enqueues all jobs.
maxon::JobGroupRef::EnqueueAndWait() : Enqueues all jobs and waits for them to finish. The same as using a group with maxon::JOBGROUPFLAGS::ENQUEUEING_THREAD_WAITS .
maxon::JobGroupRef::Wait() : Waits for the jobs to finish.
maxon::JobGroupRef::GetResult() : Returns any errors form the jobs.
maxon::JobGroupRef::Cancel() : Cancels the execution of the jobs.
maxon::JobGroupRef::CancelAndWait() : Cancels the execution of the jobs and waits for all jobs to end.
maxon::JobGroupRef::ToString() : Returns a string representation of the group.
maxon::JobGroupRef::ObservableFinished() : Returns the observable that is triggered after this job has been executed.

// This example creates a new job group and adds lambda functions to it.

// create group maxon::JobGroupRef group = maxon::JobGroupRef::Create () iferr_return ; for (const maxon ::Url& file : files) { // add lambda function group. 添加 ( [file]() { CreateFileHash(file) iferr_ignore ( "Lambda can't handle errors." _s); }) iferr_return ; }

// enqueue jobs and wait group. Enqueue (); group. Wait ();

// This example creates a new job group and adds newly created jobs to it.

// create group maxon::JobGroupRef group = maxon::JobGroupRef::Create () iferr_return ; for (const maxon ::Url& file : files) { // create and add job auto job = FileHashJob::Create(file) iferr_return ; group. 添加 (job) iferr_return ; }

// enqueue jobs and wait group. Enqueue (); group. Wait ();

// This example creates a new job group and adds generic jobs to it.

// create group maxon::JobGroupRef group = maxon::JobGroupRef::Create () iferr_return ; for (const maxon ::Url& file : files) { // add generic job defined by a lambda function maxon::JobRef job = maxon::JobRef::Create ( [file]() -> maxon::Result<void> { return CreateFileHash(file); }) iferr_return ; group. 添加 (job) iferr_return ; }

// enqueue jobs and wait group. Enqueue (); group. Wait ();

// This example creates a new job group and adds an array of jobs to it

// create group maxon::JobGroupRef group = maxon::JobGroupRef::Create () iferr_return ;

// prepare array of jobs maxon ::BaseArray<FileHashJob> jobs; jobs.EnsureCapacity(files. GetCount ()) iferr_return ; for (const maxon ::Url& file : files) { // create job FileHashJob& job = jobs.Append() iferr_return ; // init job job.SetFile(file) iferr_return ; } group. 添加 (jobs) iferr_return ;

// enqueue jobs and wait group. Enqueue (); group. Wait ();

Jobs that do belong to a job group can handle sub-jobs:

maxon::JobInterface::AddSubJob() : Adds a job to the job's group.
maxon::JobInterface::AddSubGroup() : Adds a subgroup to the job's group.
maxon::JobInterface::GetJobGroup() : Returns the group the job belongs to.

Queue

Jobs are added to a queue which executes these jobs. A queue provides worker threads and distributes the jobs.

注意: Typically it is not needed to create a custom queue. maxon::JOBQUEUE_CURRENT should be used.

Default job queues are:

maxon::JOBQUEUE_CURRENT : The current queue.
maxon::JOBQUEUE_NONE : Jobs are immediately executed on the current thread. For notifications and timer jobs.
maxon::JobQueueInterface::GetMainThreadQueue() : Returns the main thread queue. See also maxon::ExecuteOnMainThread() .
maxon::JobQueueInterface::GetServiceIOQueue() : Returns a queue for asynchronous I/O and service jobs.

It is possible to manually create queues in order to organize job execution.

maxon::JobQueueInterface : A job queue. The order of execution is not guaranteed.
maxon::SerialJobQueueRef : A job queue that guarantees serialized execution of the enqueued jobs.

注意: Functions like maxon::JobInterface::Enqueue() or maxon::JobGroupRef::Enqueue() add the job or jobs to the current job queue if no argument is given.

延伸阅读

maxon::JobGroupRef::Enqueue

JobGroupRef & Enqueue(JobQueueInterface *queue=JOBQUEUE_CURRENT)

定义： jobgroup.h:426

maxon::JobGroupRef::Add

Result< void > Add(T &&obj)

定义： jobgroup.h:522

The maxon namespace contains all declarations of the MAXON API.

定义： c4d_basedocument.h:15

#define MAXON_IMPLICIT

定义： apibase.h:168

maxon::JobResultInterface< void >::SetResult

ResultOk< void > SetResult()

定义： job.h:1022

maxon::JobGroupRef::Create

static ResultMemT< JobGroupRef > Create(JOBGROUPFLAGS flags=JOBGROUPFLAGS::DEFAULT)

定义： jobgroup.h:413

#define iferr_return

定义： resultbase.h:1434

DiagnosticOutput

#define DiagnosticOutput(formatString,...)

定义： debugdiagnostics.h:166

maxon::JobInterfaceTemplate

定义： job.h:1053

maxon::GetCount

Int GetCount(const ITERABLE &iterable)

定义： collection.h:37

maxon::Result< void >

#define iferr_ignore(...)

定义： resultbase.h:1399

maxon::JobGroupRef

Reference to a group (JobGroupInterface).

定义： jobgroup.h:401

maxon::JobGroupRef::Wait

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

定义： jobgroup.h:473

#define MAXON_LIKELY(X)

定义： compilerdetection.h:481

UInt64 UInt

unsigned 32/64 bit int, size depends on the platform

定义： apibase.h:185

maxon::JobRef::Create

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

定义： job.h:1139

Reference to a job (JobInterface).

定义： job.h:1118