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.

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

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

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.

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

Return type

Promise<void>

resume

Job.resume()

Resumes the job.

Return type

Promise<void>

requires

Job.requires(modulePaths)

Specifies module dependencies of the work function.

Arguments
  • modulePaths (string|Array) – 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.

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