Class

Job

Job

The Compute API's Job Handle (see Compute API spec) Job handles are objects which correspond to jobs. They are created by some exports of the compute module, such as compute.do and compute.for.

Extends

  • module:dcp/dcp-events.PropagatingEventEmitter

Members

object

# initialSliceProfile

An object describing the cost the user believes each the average slice will incur, in terms of CPU/GPU and I/O. If defined, this object is used to provide initial scheduling hints and to calculate escrow amounts.

module:dcp/wallet.AuthKeystore

# readonly paymentAccountKeystore

The keystore that will be used to pay for the job. Can be set with Job.setPaymentAccountKeystore or by providing a keystore to Job.exec.

# public

A place to store public-facing attributes of the job. Anything stored on this object will be available inside the work function (see module:dcp/compute~sandboxEnv.work). The properties documented here may be used by workers to display what jobs are currently being worked on.

Properties:
Name Type Description
name string

Public-facing name of this job.
description string

Public-facing description for this job.
link string

Public-facing link to external resource about this job.
object

# requirements

An object describing the requirements that workers must have to be eligible for this job. See Requirements Objects.

ResultHandle

# results

A Result Handle object used to query and manipulate the output set. Present once job has been deployed.

object

# readonly status

The current job status. Will have undefined values when the handle hasn't had exec called on it yet.

Properties:
Name Type Description
total number

Total number of slices in the job
distributed number

Number of slices that have been distributed
computed number

Number of slices that have completed execution (returned a result)
runStatus string

Current runStatus of the job
module:dcp/dcp-events.EventEmitter

# work

An EventEmitter for custom events dispatched by the work function.

Example
// in sandbox
work.emit('myEventName', 1, [2], "three");
// clientside
job.work.on('myEventName', (num, arr, string) => { });

Methods

# async cancel()

Cancel the job

# async escrow(fundsRequired)

Escrow additional funds for this job

Parameters:
Name Type Description
fundsRequired number | BigNumber

A number or BigNumber instance representing the funds to escrow for this job

# async exec(slicePaymentOfferopt, paymentAccountKeystoreopt, initialSliceProfileopt)

Deploys the job to the scheduler.

Parameters:
Name Type Attributes Default Description
slicePaymentOffer number | object <optional>
 compute.marketValue

amount in DCC that the user is willing to pay per slice.
paymentAccountKeystore keystore <optional>
 wallet.get

An instance of the Wallet API Keystore that's used as the payment account when executing the job.
initialSliceProfile object <optional>

An object describing the cost the user believes the average slice will incur.

# async getJobInfo()

Helper function for retrieving info about the job. The job must have already been deployed. An alias for module:dcp/compute.getJobInfo.

# async getSliceInfo()

Helper function for retrieving info about the job's slices. The job must have already been deployed. An alias for module:dcp/compute.getSliceInfo.

# async localExec(cores, …args) → {Promise.<ResultHandle>}

This function is identical to exec, except that the job is executed locally in the client.

Parameters:
Name Type Attributes Default Description
cores number 1

the number of local cores in which to execute the job.
args any <repeatable>

The remaining arguments are identical to the arguments of exec
  • resolves with the results of the job, rejects on an error
Promise.<ResultHandle>

# requires(modulePath)

This function specifies a module dependency (when the argument is a string) or a list of dependencies (when the argument is an array) of the work function. This function can be invoked multiple times before deployment.

Parameters:
Name Type Description
modulePath string | array

A string or array describing one or more dependencies of the job.

# async resume()

Resume this job

# setPaymentAccountKeystore(keystore)

Set the account upon which funds will be drawn to pay for the job.

Parameters:
Name Type Description
keystore module:dcp/wallet.AuthKeystore

A keystore that representa a bank account.

Events

object

# accepted

This event is emitted when the job is accepted by the scheduler on deploy.

Properties:
Name Type Description
job object

Original object that was delivered to the scheduler for deployment

# cancel

Fired when the job is cancelled.

ResultHandle

# complete

Fired when the job has been completed.

object

# console

Fired when a slice uses one of the console log functions.

Properties:
Name Type Description
address string

ID of the job
sliceIndex number

The index of the slice that produced this event
level string

The log level, one of debug, info, log, warn, or error
message string

The console log message

BigNumber

# ENOFUNDS

Fired when the job is paused due to running out of funds. The job can be resumed by escrowing more funds then resuming the job.

Event payload is the estimated funds required to complete the job

# ENOPROGRESS

Fired when the job is cancelled due to the work function not calling the progress method frequently enough.

object

# error

Fired when a slice throws an error.

Properties:
Name Type Description
address string

ID of the job
sliceIndex number

Index of the slice that threw the error
message string

The error message
stack string

The error stacktrace
name string

The error type name

# ESLICETOOSLOW

The job was cancelled because scheduler has determined that individual tasks in this job exceed the maximum allowable execution time.

# ETOOMANYERRORS

Fired when the job is cancelled because too many work functions are terminating with uncaught exceptions.

object

# noProgress

Fired when a slice is stopped for not calling progress. Contains information about how long the slice ran for, and about the last reported progress calls.

Properties:
Name Type Description
address string

ID of the job
sliceIndex number

The index of the slice that failed due to no progress
timestamp number

How long the slice ran before failing
progressReports object
last object

The last progress report received from the worker
last.timestamp number

Time since the start of the slice
last.progress number

Progress value reported
last.value *

The last value that was passed to the progress function
last.throttledReports number

Number of calls to progress that were throttled since the last report
lastUpdate object

The last determinate (update to the progress param) progress report received from the worker
lastUpdate.timestamp number
lastUpdate.progress number
lastUpdate.value *
lastUpdate.throttledReports number

object

# noProgressData

Identical to noProgress, except that it also contains the data that the slice was executed with.

Properties:
Name Type Description
data *

The data that the slice was executed with

object

# result

Fired when a result is returned.

Properties:
Name Type Description
address string

ID of the job
task string

ID of the task (slice) the result came from
sort number

The index of the slice
result object
request string
result *

The value returned from the work function

# resultsUpdated

Fired when the result handle is modified, either when a new result event is fired or when the results are populated with results.fetch()

object

# status

Fired when the job's status changes.

Properties:
Name Type Description
address string

ID of the job
total number

Total number of slices in the job
distributed number

Number of slices that have been distributed
computed number

Number of slices that have completed execution (returned a result)
runStatus string

Current runStatus of the job