digitalbazaar/bedrock-jobs

Name: bedrock-jobs

Owner: Digital Bazaar, Inc.

Description: Bedrock jobs

Created: 2015-01-13 23:35:56.0

Updated: 2016-03-03 14:31:05.0

Pushed: 2017-03-01 04:45:19.0

Homepage: null

Size: 50

Language: JavaScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

bedrock-jobs

A bedrock module that exposes an API for scheduling and executing background jobs.

Requirements

• npm v3+

Quick Examples

install bedrock-jobs

s
bedrock = require('bedrock');

ire('bedrock-mongodb');
scheduler = require('bedrock-jobs');

ock.config.scheduler.jobs.push({
: 'myproject.jobs.Scan',
pe: 'myproject.jobs.Scan',
 repeat forever, run every minute
hedule: 'R/PT1M',
 no special priority
iority: 0,
 no concurrency limit, every bedrock worker can run one of these jobs
ncurrency: -1


ock.events.on('bedrock.init', function() {
 define job type so it will run in this bedrock instance
heduler.define('myproject.jobs.Scan', function(job, callback) {
doSomeKindOfScan(function(err) {
  // scan finished
  callback(err);
});
;

Configuration

Jobs can be automatically scheduled by specifying job objects in bedrock.config.scheduler.jobs.

For more documentation on configuration, see config.js.

API

define(type, [options], fn)

Defines a new job type. Schedules jobs will only be processed if their types have been defined. A job type (a unique string) specifies:

• The function that will be run to process a job of that type.
• How many workers can run a job of that type at the same time (i.e. the the total number of work permits for the job type).
• How long a particular worker that is running a job of that type may run before being considered expired, forcibly releasing its permit to allow another worker to work on the job.

Note that, due to current implementation limitations, lock duration can only be configured on a per-job-type basis, it cannot be configured per-job.

The options may include:

• lockDuration how long, in milliseconds, a worker for a job of this type may execute before its permit is forcibly released, there by permitting another worker to execute the job.
• defaults default job values to use:
• schedule how often to run the job; schedules must be given as strings in ISO 8601 time interval format.
• priority a number indicating priority, 0 for default, negative for low, positive for high.
• concurrency the number of workers that can concurrently work on a job, -1 for unlimited.

Any options.defaults given will override the defaults specified by bedrock.config.scheduler.defaults.

The fn parameter is a function to call to execute the job. It takes a job object and a callback as parameters. Once the job completes (or an error occurs that causes it to stop), the callback must be called. If an error occurs, it should be passed to the callback.

generateJobId(callback)

Creates a new job ID. The callback will be called once the ID is ready or if an error occurs. The first parameter will be an error or null and the second will be the ID.

schedule(job, [options], callback)

Schedules a new job. The job must have a type set (job.type). It may specify a unique id, if it does not, one will be generated. It may also specify how often to run the job and any job-specific data. The job will be passed to the function that was previously passed to define to define its type.

Jobs may be scheduled that do not have defined types, however, they will never be executed by this particular scheduler (other schedulers may execute them). This allows distributed systems that share a common database to be configured such that some machines will execute certain types of jobs that are found in the database whilst others will not. For example, one machine may only run jobs of type A and one machine may only run jobs of type B, but both may be capable of scheduling either type of job.

The options may include:

• immediate true to run the job immediately if its schedule permits.

The callback will be called once the scheduling operation completes or if an error occurs. If an error occurred, it will be passed to the callback.

unschedule(options, callback)

Unschedules a job or all jobs of a certain type. The options parameter must be given any have either:

• id the id of the job to unschedule, or
• type the type of jobs to unschedule.

The callback will be called once the operation completes. If an error occurs, it will be passed to the callback.