work

A first-in-first-out async task queue. Fill the queue with Task instances (using module:work.TaskQueue#push) then (when ready) call module:work.TaskQueue#process to settle each task in the order they were received. During processing, the queue will process module:work.TaskQueue#maxConcurrent tasks at a time. Each task comprises a name, deferred and list of resolvers - each of which will race to settle the deferred first.

Example

var tq = require("work")
var q = require("q")
var http = require("http")
 
var queue = new tq.TaskQueue()
 
// get the football results - it will take between 0 and 2000ms 
// and resolve with the result 
function resultResolver(deferred){
    setTimeout(function(){
        deferred.resolve("West Ham 1 - Tottenham Hotspur 3")
    }, Math.random() * 2000)
}
 
// but the timeout resolver will reject it after 1000ms 
function timeoutResolver(deferred){
    setTimeout(function(){
        deferred.reject(Error("timeout"))
    }, 1000)
}
 
var task = new tq.Task({
    name: "get result",
    resolver: [ resultResolver, timeoutResolver ]
})
 
queue.push(task)
 
task.promise
    .then(function(result){
        console.log(result)
    })
    .catch(function(err){
        console.log("It failed: " + err.message)
    })
 
queue.process()

• work
  • .Queue
    • new Queue([options])
    • .name : string
    • .queued : Array
    • .active : Array
    • .maxConcurrent : number
    • .length : number
    • .freeSlotCount : number
    • .push(task) ↩︎
    • .shift() ⇒ Task
    • .process()
    • .unshift(newTask) ⇒ Task
    • .cancel() ⇒ Task
    • .isEmpty() ⇒
    • "occupied"
    • "push"
    • "empty"
    • "complete"
    • "shift"
    • "occupied"
    • "unshift"
    • "empty"
    • "cancel"
  • .Task ⇐ module:state-machine
    • new Task(executor, [options])
    • instance
      • .promise : external:Promise
      • .name : string
      • .context : string
      • .process()
      • .cancel()
      • "fulfilled"
      • "resolved"
      • "rejected"
      • "running"
    • static
      • .eState : enum

tq.Queue

queue class for processing promises

Kind: static class of work

• .Queue
  • new Queue([options])
  • .name : string
  • .queued : Array
  • .active : Array
  • .maxConcurrent : number
  • .length : number
  • .freeSlotCount : number
  • .push(task) ↩︎
  • .shift() ⇒ Task
  • .process()
  • .unshift(newTask) ⇒ Task
  • .cancel() ⇒ Task
  • .isEmpty() ⇒
  • "occupied"
  • "push"
  • "empty"
  • "complete"
  • "shift"
  • "occupied"
  • "unshift"
  • "empty"
  • "cancel"

new Queue([options])

queue.name : string

useful for debugging

Kind: instance property of Queue

queue.queued : Array

the current task queue

Kind: instance property of Queue

queue.active : Array

The in-progress tasks

Kind: instance property of Queue

queue.maxConcurrent : number

when emptying, specifying the max number of tasks which may run simultaneously.

Kind: instance property of Queue
Default: 1

queue.length : number

queue length

Kind: instance property of Queue

queue.freeSlotCount : number

Kind: instance property of Queue

queue.push(task) ↩︎

add a task to the end of the queue

Kind: instance method of Queue
Chainable

queue.shift() ⇒ Task

returns the next task in the queue and adds it to the active list.

Kind: instance method of Queue

queue.process()

process the queue - attempt to resolve each task.

Kind: instance method of Queue
Todo

• return a promise which resolves on completion

queue.unshift(newTask) ⇒ Task

insert a task at the front of the queue, returning the instance inserted

Kind: instance method of Queue

queue.cancel() ⇒ Task

Shifts the next task off the queue and calls .cancel() on it

Kind: instance method of Queue

queue.isEmpty() ⇒

Test whether any tasks are queued or active

Kind: instance method of Queue
Returns: boolean

"occupied"

Emitted at the moment a queue becomes occupied (has at least 1 task)

Kind: event emitted by Queue

"push"

Emitted when a task is added

Kind: event emitted by Queue

"empty"

Emitted after the final task is taken off the queue for processing

Kind: event emitted by Queue

"complete"

Emitted when the queue processing is complete

Kind: event emitted by Queue

"shift"

Emitted when a task is shifted

Kind: event emitted by Queue

"occupied"

Emitted at the moment a queue becomes occupied (has at least 1 task)

Kind: event emitted by Queue

"unshift"

Emitted when a task is unshifted to the front of the queue

Kind: event emitted by Queue

"empty"

Emitted after the final task is taken off the queue for processing

Kind: event emitted by Queue

"cancel"

Emitted when a task is cancelled

Kind: event emitted by Queue

tq.Task ⇐ module:state-machine

A task defines a piece of work which needs doing now, or in the future. When you create a task you receive a promise for its result. Process the task using task.process().

Kind: static class of work
Extends: module:state-machine

• .Task ⇐ module:state-machine
  • new Task(executor, [options])
  • instance
    • .promise : external:Promise
    • .name : string
    • .context : string
    • .process()
    • .cancel()
    • "fulfilled"
    • "resolved"
    • "rejected"
    • "running"
  • static
    • .eState : enum

new Task(executor, [options])

task.promise : external:Promise

a promise for the completion of the task

Kind: instance property of Task

task.name : string

useful for debug output

Kind: instance property of Task

task.context : string

data for the task

Kind: instance property of Task

task.process()

Process the task - settled the deferred using the supplied resolver function(s). The resolver function is called in the context of the task and receives a deferred, which must be resolved.

Kind: instance method of Task

task.cancel()

a cancelled task fulfils with the value -1

Kind: instance method of Task

"fulfilled"

Emitted when a task fulfills

Kind: event emitted by Task

"resolved"

Emitted when a task is resolved

Kind: event emitted by Task

"rejected"

Emitted when a task is rejected

Kind: event emitted by Task

"running"

Emitted when a task starts

Kind: event emitted by Task

Task.eState : enum

The various Task states.

Kind: static enum property of Task
Properties

© 2015 Lloyd Brookes <75pound@gmail.com>. Documented by jsdoc-to-markdown.