Job

class Job()

The Compute API’s Job Handle (see {@link https://docs.dcp.dev/specs/compute-api.html#job-handles|Compute API spec}) Job handles are objects which correspond to jobs. They are created by some exports of the compute module, such as {@link module:dcp/compute.do|compute.do} and {@link module:dcp/compute.for|compute.for}.

Attributes

Note

job.id is a getter for job.address, so they’re effectively the same.

Job.localWorker

A Worker object that describes the local worker if one is used for a job.

requirements

Job.requirements

An object that describes the requirements a worker must have to be eligible for the job.

Requirements include:

  • fdlibm capability

  • offscreenCampus definition

  • WebGL MAX_TEXTURE_SIZE

  • JavaScript engine type

public

Job.public

An object to store public-facing attributes of a job. Anything stored in this object will be available for use inside the work function. Properties of this object can be seen by the worker in order to display what job it is currently working on.

Job.public.name

Public-facing name of the job.

Type:

string

Job.public.description

Public-facing description of the job.

Type:

string

Public-facing link to an external resource about the job.

Type:

string

Example:

const job = compute.for(inputSet, workFn);
job.public.name = `DCP for Physics!`;
job.public.description = `Using DCP for electromagnetic force calculations`;
job.public.link = MY_RESEARCH_URL;

useStrict

const job = compute.for(inputSet, workFn);
job.useStrict = true;
Job.useStrict

Setting Job.useStrict true runs the work function in the strict mode. :type: boolean

Tutorials:

Methods

job.on

The Job Handle class extends Node.js’ EventEmitter class, thus emitter.on is available on an instance of a Job Handle.

See https://nodejs.org/api/events.html#events_emitter_on_eventname_listener for more info.

These are the following events that job.on() can listen for:

  • accepted

    • emitted when the job gets accepted by the DCP Scheduler

  • complete

    • emitted when the job finishes

  • readystatechange

    • emitted leading up to deployment of the job

  • console

    • used to collect the console output of the workers

  • result

    • emitted when a slice completes and returns

Example:

job.on('readystatechange', (ev) => {
   console.log(`Ready state: ${ev}`);
});

Tutorials:

exec

Job.exec(slicePaymentOffer=compute.marketValue, paymentAccountKeystore=wallet.get(), initialSliceProfile=undefined)

Deploys the job to the scheduler for work to be done by distributed workers all throughout the DCP network.

Arguments:

  • slicePaymentOffer (number|object) – The amount of DCC user is willing to pay per slice.

  • paymentAccountKeystore (Keystore) – Instance of Wallet API Keystore being used as the payment account for executing a job.

  • initialSliceProfile (object) – Object describing the cost the user believes the average slice will incur in terms of CPU/GPU and I/O.

Return type:

Promise<ResultHandle()>

Example:

const { init } = require('dcp-client');

init().then(async (dcp) => {
  const compute = require('dcp/compute');
  // or
  // const { compute } = dcp;
  const iterable = [1, 2, 3, 4, 5];
  const job = compute.for(
    iterable,
    async (sliceIndex, data) => {
      progress();
      return sliceIndex ** 2 + Math.sqrt(data);
    },
    [100],
  );
  const results = await job.exec();
});

Tutorials:

localExec

Job.localExec(cores=1, slicePaymentOffer=compute.marketValue, paymentAccountKeystore=wallet.get(), initialSliceProfile=undefined)

Deploys the job for work to be done in locally in the client.

Arguments:

  • cores (number) – The number of local cores to be used to execute the job.

  • slicePaymentOffer (number|object) – The amount of DCC user is willing to pay per slice. However, localExec jobs don’t take DCC.

  • paymentAccountKeystore (Keystore) – Instance of Wallet API Keystore being used as the payment account for executing a job.

  • initialSliceProfile (object) – Object describing the cost the user believes the average slice will incur in terms of CPU/CPU and I/O.

Return type:

Promise<ResultHandle()>

Warning

2021-12-14: We are aware of an issue where localExec() does not work on Windows systems. We are working to resolve this.

Note

Running a DCP job on localExec() requires dcp-worker to be installed in the project repository.

npm i dcp-worker

Example:

const { init } = require('dcp-client');

init().then(async (dcp) => {
  const compute = require('dcp/compute');
  // or
  // const { compute } = dcp;
  const iterable = [1, 2, 3, 4, 5];
  const job = compute.for(
    iterable,
    async (sliceIndex, data) => {
      progress();
      return sliceIndex ** 2 + Math.sqrt(data);
    },
    [100],
  );
  const results = await job.localExec();
});

cancel

Job.cancel(reason='')

Cancels the job on the scheduler end. No additional slices from the job will be sent to any workers.

Arguments:

  • reason (string) – The reason for job cancellation, sent to client if provided.

Return type:

Promise<void>

This can be used to cancel jobs returning unpredictable, or incorrect results. This can save DCCs if you cancel a job before all the slices are complete, but after you know that the results won’t be useful in some way. Example:

/*
 * Example that cancels a job if any result that gets returned is not a number.
 */
const job = compute.for(inputSet, workFn);

job.on('result', function (ev) {
  if (typeof ev !== 'number') {
    job.cancel('Unexpected results, expected number');
  }
});

resume

Job.resume()

Resumes the job.

Return type:

Promise<void>

Warning

job.resume() is not yet implemented in v4.

requires

Job.requires(modulePaths)

Specifies module dependencies of the work function.

Arguments:

  • modulePaths (string|Array<string>) – Either a string or a list of strings that represent the module dependency path.

Note

modulePaths should not have .js extension at the end of the path. For more information on moduleIdentifiers, view the CommonJs specification here

Example:

const job = compute.for(['apple', 'banana', 'pineapple'], function work(data) {

   let mid = require(`./reverser`)
   progress();
   return mid.reverse(data)
  });

job.requires('./reverser')

Events

"status"

event

An object that contains relevant information about the job and its slices.

event.total

Total number of slices in the job.

Type:

number

event.distributed

Number of slices that have been distributed.

Type:

number

event.computed

Number of slices that have completed execution and returned a result.

Type:

number

event.runStatus

The current run status of the job (e.g. estimation, running, finished, etc.).

Type:

string

Example:

const job = compute.for(inputSet, workFn);

job.on('status', () => {
  console.log(job.status);
});