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 and job.address are not the same thing, and neither is a getter for the other. id is an opaque string generated locally as soon as the Job is created (present immediately, before deployment) – it’s what compute.cancel/compute.resume/compute.getJobInfo expect. address is a separate, scheduler-assigned identifier (the job’s escrow address) that only exists once the job has been deployed. See Job Handles in the Compute API spec for the full property list.

Job.localWorker

A DistributiveWorker (see the Worker API) instance created internally when Job.localExec() is used. undefined otherwise.

requirements

See Requirements Object Properties in the Compute API spec for the current, authoritative list – it changes independently of this page and the typedef is explicitly marked private/unstable in its own source comments.

Job.requirements

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

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.

job.on() can listen for accepted, cancel, result, resultsUpdated, complete, status, error, console, noProgress, noProgressData, and nofunds – see Job Handles Events in the Compute API spec for the full, current list with payload shapes; this page doesn’t duplicate it to avoid the two drifting apart.

Example:

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

Tutorials:

  • Web: Times Two

exec

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

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. Only applied if it’s a number or object – passing nothing leaves whatever was set earlier (e.g. via setSlicePaymentOffer) in place.

  • paymentAccountKeystore (Keystore) – Instance of Wallet API Keystore being used as the payment account for executing a job. Only applied if given – there is no wallet.get() fallback inside exec() itself.

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

See exec under Job Handles (Methods) in the Compute API spec for the fuller, kept-in-sync description of this method’s parameters and behavior.

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, ...args)

Identical to exec(), except that the job runs locally (in-process, via an internal DistributiveWorker) instead of being deployed to the scheduler.

Arguments:

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

  • args – The remaining arguments are passed through to exec() as-is.

Return type:

Promise<ResultHandle()>

Note

localExec() unconditionally sets the slice payment offer to 0 and uses a fresh, empty-passphrase Keystore for payment before forwarding args to exec() – any slicePaymentOffer/paymentAccountKeystore you pass are used by exec()’s own logic same as always, but there’s no real money involved either way since nothing is deployed to the scheduler.

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() references a connection property that is never initialized on the Job instance, and currently throws if called. Re-calling exec() on the same Job Handle is the working way to resume a job paused for nofunds – see the resume entry under Job Handles (Methods) in the Compute API spec.

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

Id of the job (Job.id).

Type:

string

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);
});