Queue

Queue is an abstract Job factory bound to a request data source represented by the asynchronous peek () method.

The basic idea behind Queue is decoupling Job creation from the flow of incoming signals: they cannot have any payload, request parameters are fetched from a known data store; if it's empty or some work is in progress, new signals are silently ignored, but with each job completed, a new request is scheduled.

The Queue's basic functionality (implemented as the check () method) is to produce a Job that peek ()s its parameters on init, handles them and schedules the next check upon its completion. This loop breaks when yet another peek () returns null. After that, if the queue storage is refilled, an external call to check () is required to resume the process.

If the cron option is set, the croner module is used to call check () periodically. Otherwise, some other means must be used to decide when to invoke check (): for instance, notifications on appending content to the queue. croner related timers are cleaned up on the Application's 'finish' event.

For a Queue, maxPending is 1 by default and it is recommended to leave it so in general: otherwise, one need some additional locking to prevent Job duplication. Unlike the generic JobSource's createJob, Queue's check never throws JobSource.OverflowError: while existing job(s) are in progress, subsequent check () calls are just no-ops. In case of JobSource.LockedError, it will be rethrown though.

Options

JobSource's options

Name	Type	Default	Description
cron	String	undefined	A cron like pattern, argument to create a croner instance

Methods

check ()

This synchronous method tries to createJob () with default parameters and immediately launch job.outcome (). When JobSource.OverflowError is caught, exits silently. The return value is always undefined.

onJobInit (job)

This asynchronous method, scheduled to init for every Job created, tries to fetch the request object with peek () and,

• is it's null, breaks the execution by setting job.request = null;
• otherwise, merges its content into job.request and schedules onJobNext () to the next event.

onJobNext ()

Calls this.check ()

peek (job)

This asynchronous method must return either null (meaning the queue is empty) or a non-null Object to be merged into job.request.

The same Object must be returned by peek () repeatedly unless properly handled or temporarily locked: it's up to the job to somehow move it out of peek ()'s visibility.

The job parameter is available to the peek method to provide it with the job's context: mostly, resources, such as database connections. peek () should not alter the job's state. The request property is updated by onJobInit.

In the base implementation, returns null.