for

compute.for(start, end, step, work, args)
compute.for(remoteDataset, work, args)
compute.for(iterableObject, work, args)
compute.for(rangeObject, work, args)
compute.for(multiRange, work, args)

Creates a Job for the distributed computer using one of multiple forms.

Multiple forms are given for creating a job to give flexibility in the types of inputs and formats the inputs accepted. By using one of the range object types, one can do extremely large ranges without having to hold indices in memory. Additionally, with function * generators one can format inputs as coming from a variety of sources and only read the sources when needed.

Arguments
  • start (number) – First number in the range.

  • end (number) – Last number in the range.

  • step (number) – The space between numbers in the range.

  • remoteDataset (RemoteDataSet) – Array, ES6 function* generator, or any other type of iterable object. Where each iteration is a slice that will be run on the work function.

  • iterableObject (iterable object) – Array|ES6 function* generator|or any other type of iterable object. Where each iteration is a slice that will be run on the work function.

  • rangeObject (RangeObject) – Either a RangeObject() or an object literal which can be used to create a RangeObject().

  • multiRange (MultiRangeObject) – Either a MultiRangeObject() or any valid argument to the constructor.

  • work (function|string|URL|DcpURL) – Work function that will be run on each slice.

  • args (array-like object) – Array-like object which contains arguments that are passed to the work function (along with the slice’s datum).

Return type

Job()

Note

compute.for() is useful for most DCP jobs. However, when the input set is 1..n, when the input to each slice does not matter for the work done, or when the job has only one slice, compute.do() may be more useful.

Forms

Form 1

Creates a job that iterates through a RangeObject() with the properties specified in start, end, and step.

for(start, end, step, work, args = []) => Job

Arguments:

  • start (number) - First number in the range.

  • end (number) - Last number in the range.

  • step (Number) - The space between numbers in the range.

  • work (function|string|URL|DcpURL) - The work function to run. on each slice. Can be a function string literal or a URL that points to a function fetched by the worker.

  • args (Array-Like Object) - Array-like object which contains arguments passed to the work function (along with the slice index).

Example:

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

init().then((dcp) => {
  const compute = require('dcp/compute');
  // or
  // const { compute } = dcp;

  const job = compute.for(
    1,
    1000,
    2,
    async (sliceIndex, data) => {
      progress();
      return sliceIndex ** 2 + Math.sqrt(data);
    },
    [100],
  );
});

Tutorials:

Form 2

Creates a job that iterates through a RemoteDataSet. Each URL object iterated over in the RemoteDataSet tells the worker where the fetch the input data passed into the work function for each slice.

for(remoteDataSet, work, args = []) => Job

Arguments:

  • remoteDataSet (RemoteDataSet) - An Array-like object of URI strings that point at data to fetched by the worker for input.

  • work (function|string|URL|DcpURL) - The work function to run. on each slice. Can be a function string literal or a URL that points to a function to fetched by the worker.

  • args (Array-Like Object) - Array-like object which contains arguments passed to the work function (along with the slice’s input datum).

Example:

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

init().then((dcp) => {
  const compute = require('dcp/compute');
  // or
  // const { compute } = dcp;
  const remoteData = ['https://example.com/data'];
  const remoteDataSet = new compute.RemoteDataSet(...remoteData);
  const job = compute.for(
    remoteDataset,
    async (data) => {
      progress();
      console.log(data);
      return data;
    },
    [100],
  );
});

Form 3

Creates a job that runs through an iterable object. Each value upon iteration become arguments for the work function. If the entire iterable object consists of (must be homogeneous) URL objects or DcpURL objects, all data pointed to by the URL is automatically fetched as input per slice.

for(iterableObject, work, args = []) => Job

Arguments:

  • iterableObject (Array|ES6 function generator|Iterable Object) - Array, ES6 function* generator, or any other iterable object, where each iteration is a slice that’s ran on the work function.

  • work (function|string|URL|DcpURL) - The work function to run on each slice. Can be a function string literal or a URL that points to a function to fetched by the worker.

  • args (Array-Like Object) - Array-like object which contains arguments passed to the work function (along with the slice’s data).

Example:

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

init().then((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],
  );
});

Tutorials:

Form 4

Creates a job that iterates through a :class:RangeObject.

for(rangeObject, work, args = []) => Job

Arguments:

  • rangeObject (RangeObject()|object) - Either a RangeObject() or an object literal which is RangeObject()-like.

  • work (function|string|URL|DcpURL) - The work function to run on each slice. Can be a function string literal or a URL that points to a function fetched by the worker.

  • args (Array-Like Object) - Array-like object which contains arguments passed to the work function (along with the slice’s datum).

Example:

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

init().then((dcp) => {
  const compute = require('dcp/compute');
  // or
  // const { compute } = dcp;

  const { RangeObject } = require('dcp/range-object');

  const rangeObject = new RangeObject(1, 1000, 2);
  const job = compute.for(
    rangeObject,
    async (sliceIndex, data) => {
      progress();
      return sliceIndex ** 2 + Math.sqrt(data);
    },
    [100],
  );
});

Form 5

Creates a job that iterates through a MultiRangeObject() similarly to iterating through nested loops. A MultiRangeObject() is essentially a multi-dimensional RangeObject().

for(multiRange, work, args = []) => Job

Arguments:

  • multiRange (MultiRangeObject()|object) - Either a MultiRangeObject() or any valid argument to the constructor.

  • work (function|string|URL|DcpURL) - The work function to run on each slice. Can be a function string literal or a URL that points to a function fetched by the worker.

  • args (Array-Like Object) - Array-like object which contains arguments passed to the work function (along with the slice’s input datum).

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

init().then((dcp) => {
  const compute = require('dcp/compute');
  // or
  // const { compute } = dcp;

  const { RangeObject, MultiRangeObject } = require('dcp/range-object');

  const rangeObject1 = new RangeObject(1, 1000, 2);
  // [1, 3, 5, 7, ..., 999]
  const rangeObject2 = new RangeObject(0, 1000, 2);
  // [0, 2, 4, 6, ..., 1000]

  const multiRange = new MultiRangeObject(rangeObject1, rangeObject2);
  // [[1,0], [1,1], [1,2]...., [1,1000], [2,0], [2,1], ...]

  const job = compute.for(
    multiRange,
    async (sliceIndex, data) => {
      progress();
      return sliceIndex[0] ** 2 + sliceIndex[1] ** 2 + Math.sqrt(data);
    },
    [100],
  );
});

Each work function passed into compute.for() needs to include a call to the progress() function.