Class Task

Defined in: src/lib/taskgroup.coffee
Inherits: Interface

Overview

Public: Our Task Class. Available configuration is documented in ::setConfig. Available events: - `started()` - emitted when we start execution - `running()` - emitted when the method starts execution - `failed(err)` - emitted when execution exited with a failure - `passed()` - emitted when execution exited with a success - `completed(err, args...)` - emitted when execution exited, `args` are the result arguments from the method - `error(err)` - emtited if an unexpected error occurs without ourself - `done(err, args...)` - emitted when either execution completes (the `completed` event) or when an unexpected error occurs (the `error` event) Available internal statuses: - `null` - execution has not yet started - `'started'` - execution has begun - `'running'` - execution of our method has begun - `'failed'` - execution of our method has failed - `'passed'` - execution of our method has succeeded - `'destroyed'` - we've been destroyed and can no longer execute Examples task = require('taskgroup').Task.create('my synchronous task', -> return 5 ).done(console.log) # null, 5] task = require('taskgroup').Task.create('my asynchronous task', (complete) -> complete(null, 5) ).done(console.log) # [null, 5] task = require('taskgroup').Task.create('my task that errors', -> err = new Error('deliberate error') return err // if asynchronous, can also do: complete(err) // thrown and uncaught errors are also caught thanks to domains, but that should be avoided // as it would put your app in an unknown state ).done(console.log) # [Error('deliberator error')]

Examples:

task = require('taskgroup').Task.create('my synchronous task', ->
  return 5
).done(console.log)  # null, 5]

task = require('taskgroup').Task.create('my asynchronous task', (complete) ->
  complete(null, 5)
).done(console.log)  # [null, 5]

task = require('taskgroup').Task.create('my task that errors', ->
  err = new Error('deliberate error')
  return err  // if asynchronous, can also do: complete(err)
  // thrown and uncaught errors are also caught thanks to domains, but that should be avoided
  // as it would put your app in an unknown state
).done(console.log)  # [Error('deliberator error')] 

Class Method Summary

Instance Method Summary

Inherited Method Summary

Methods inherited from Interface

.whenDone, .onceDone, .done, .getNames, .getName, .getConfig

Class Method Details

Task .create(args...) Source

Public: Creates a new Task instance. args - The Arguments to forwarded along to the ::constructor. Returns the new Task instance.

Parameters:

  • argsThe Arguments to forwarded along to the ::constructor.

Returns:

  • (Task) — Returns the new Task instance.

Boolean .isTask(item) Source

Public: A helper method to check if the passed argument is an instanceof a Task. item - The possible instance of the Task that we want to check Returns a Boolean of whether or not the item is a Task instance.

Parameters:

  • (Task) itemThe possible instance of the Task that we want to check

Returns:

  • (Boolean) — Returns a Boolean of whether or not the item is a Task instance.

Constructor Details

::constructor(args...) Source

Public: Initialize our new Task instance. Forwards arguments onto ::setConfig.

Instance Method Details

::destroy() Source

Public: Destroy the task and prevent it from executing ever again.

Boolean ::hasExited() Source

Public: Have we finished its execution yet? Returns a Boolean which is `true` if we have finished execution

Returns:

  • (Boolean) — Returns a Boolean which is true if we have finished execution

Boolean ::hasStarted() Source

Public: Have we started execution yet? Returns a Boolean which is `true` if we have commenced execution

Returns:

  • (Boolean) — Returns a Boolean which is true if we have commenced execution

Boolean ::isComplete() Source

Public: Have we completed its execution yet? Returns a Boolean which is `true` if we have completed

Returns:

  • (Boolean) — Returns a Boolean which is true if we have completed

Boolean ::isDestroyed() Source

Public: Have we been destroyed? Returns a Boolean which is `true` if we have bene destroyed

Returns:

  • (Boolean) — Returns a Boolean which is true if we have bene destroyed

::onceDone(listener) Source

Public: Once Done Promise. Fires the listener once, either on the next tick if we are already done, or if not, once the `done` event fires. listener - The Function to attach or execute.

Parameters:

  • (Function) listenerThe Function to attach or execute.

::run() Source

Public: Start the execution of the task. Will emit an `error` event if the task has already started before.

::setConfig(opts = {}) Source

Public: Set the configuration for our instance. Despite accepting an Object of configuration, we can also accept an Array of configuration. When using an array, a String becomes the :name, a Function becomes the :method, and an Object becomes the :config config - Our configuration Object can contain the following fields: :name - (default: null) A String for what we would like our name to be, useful for debugging. :done - (default: null) A Function that we would like passed to ::onceDone (aliases are :onceDone, and :next) :whenDone - (default: null) A Function that we would like passed to ::whenDone :on - (default: null) An Object of (eventName => listener) that we would like bound via EventEmitter.on. :once - (default: null) An Object of (eventName => listener) that we would like bound via EventEmitter.once. :method - (default: null) The Function that we would like to execute within our task. :parent - (default: null) A parent TaskGroup that we may be attached to. :onError - (default: 'exit') A String that is either `'exit'` or `'ignore'`, when `'ignore'` duplicate run errors are not reported, useful when combined with the timeout option. :args - (default: null) An Array of arguments that we would like to forward onto our method when we execute it. :timeout - (default: null) A Number of millesconds that we would like to wait before timing out the method. :ambi - (default: true) A Boolean for whether or not to use bevry/ambi to determine if the method is asynchronous or synchronous and execute it appropriately :domain - (default: true) A Boolean for whether or not to wrap the task execution in a domain to attempt to catch background errors (aka errors that are occuring in other ticks than the initial execution) :sync - (default: false) A Boolean for whether or not we should execute certain calls asynchronously (`false`) or synchronously (`true`)

Parameters:

  • (Object) configOur configuration Object can contain the following fields:
    • (String) name(default: null) A String for what we would like our name to be, useful for debugging.
    • (Function) done(default: null) A Function that we would like passed to ::onceDone (aliases are :onceDone, and :next)
    • (Function) whenDone(default: null) A Function that we would like passed to ::whenDone
    • (Object) on(default: null) An Object of (eventName => listener) that we would like bound via EventEmitter.on.
    • (Object) once(default: null) An Object of (eventName => listener) that we would like bound via EventEmitter.once.
    • (Function) method(default: null) The Function that we would like to execute within our task.
    • (TaskGroup) parent(default: null) A parent TaskGroup that we may be attached to.
    • (String) onError(default: 'exit') A String that is either 'exit' or 'ignore', when 'ignore' duplicate run errors are not reported, useful when combined with the timeout option.
    • (Array) args(default: null) An Array of arguments that we would like to forward onto our method when we execute it.
    • (Number) timeout(default: null) A Number of millesconds that we would like to wait before timing out the method.
    • (Boolean) ambi(default: true) A Boolean for whether or not to use bevry/ambi to determine if the method is asynchronous or synchronous and execute it appropriately
    • (Boolean) domain(default: true) A Boolean for whether or not to wrap the task execution in a domain to attempt to catch background errors (aka errors that are occuring in other ticks than the initial execution)
    • (Boolean) sync(default: false) A Boolean for whether or not we should execute certain calls asynchronously (false) or synchronously (true)

::whenDone(listener) Source

Public: When Done Promise. Fires the listener, either on the next tick if we are already done, or if not, each time the `done` event fires. listener - The Function to attach or execute.

Parameters:

  • (Function) listenerThe Function to attach or execute.