Jobs Manual

Table of Contents

• About
• Job
• Job Group
• Queue
• Further Reading

About

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.

Warning

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.Add(
        [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.Add(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.Add(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.Add(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.

Note

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.

Note

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

Further Reading

• Threading
• Maxon API Threading
• Parallel Manual
• Threads Manual