Global

Members

(constant) all

A cancelation-aware variant of Promise.all. The normal version of a Promise.all just returns a regular, uncancelable Promise. The ember-concurrency variant of all() has the following additional behavior:

  • if the task that yielded all() is canceled, any of the TaskInstances passed in to all will be canceled
  • if any of the TaskInstances (or regular promises) passed in reject (or are canceled), all of the other unfinished TaskInstances will be automatically canceled.

Check out the "Awaiting Multiple Child Tasks example"

Source:

(constant) allSettled

A cancelation-aware variant of RSVP.allSettled. The normal version of a RSVP.allSettled just returns a regular, uncancelable Promise. The ember-concurrency variant of allSettled() has the following additional behavior:

  • if the task that yielded allSettled() is canceled, any of the TaskInstances passed in to allSettled will be canceled
Source:

(constant) hash

A cancelation-aware variant of RSVP.hash. The normal version of a RSVP.hash just returns a regular, uncancelable Promise. The ember-concurrency variant of hash() has the following additional behavior:

  • if the task that yielded hash() is canceled, any of the TaskInstances passed in to allSettled will be canceled
  • if any of the items rejects/cancels, all other cancelable items (e.g. TaskInstances) will be canceled
Source:

(constant) race

A cancelation-aware variant of Promise.race. The normal version of a Promise.race just returns a regular, uncancelable Promise. The ember-concurrency variant of race() has the following additional behavior:

  • if the task that yielded race() is canceled, any of the TaskInstances passed in to race will be canceled
  • once any of the tasks/promises passed in complete (either success, failure, or cancelation), any of the TaskInstances passed in will be canceled

Check out the "Awaiting Multiple Child Tasks example"

Source:

Methods

didCancel(error) → {Boolean}

Returns true if the object passed to it is a TaskCancelation error. If you call someTask.perform().catch(...) or otherwise treat a TaskInstance like a promise, you may need to handle the cancelation of a TaskInstance differently from other kinds of errors it might throw, and you can use this convenience function to distinguish cancelation from errors.

click() {
  this.get('myTask').perform().catch(e => {
    if (!didCancel(e)) { throw e; }
  });
}
Parameters:
Name Type Description
error Object

the caught error, which might be a TaskCancelation

Source:
Returns:
Type
Boolean

task(generatorFunction) → {TaskProperty}

A Task is a cancelable, restartable, asynchronous operation that is driven by a generator function. Tasks are automatically canceled when the object they live on is destroyed (e.g. a Component is unrendered).

To define a task, use the task(...) function, and pass in a generator function, which will be invoked when the task is performed. The reason generator functions are used is that they (like the proposed ES7 async-await syntax) can be used to elegantly express asynchronous, cancelable operations.

You can also define an Encapsulated Task by passing in an object that defined a perform generator function property.

The following Component defines a task called myTask that, when performed, prints a message to the console, sleeps for 1 second, prints a final message to the console, and then completes.

import { task, timeout } from 'ember-concurrency';
export default Component.extend({
  myTask: task(function * () {
    console.log("Pausing for a second...");
    yield timeout(1000);
    console.log("Done!");
  })
});
<button {{action myTask.perform}}>Perform Task</button>

By default, tasks have no concurrency constraints (multiple instances of a task can be running at the same time) but much of a power of tasks lies in proper usage of Task Modifiers that you can apply to a task.

Parameters:
Name Type Description
generatorFunction function

the generator function backing the task.

Source:
Returns:
Type
TaskProperty

taskGroup() → {TaskGroup}

"Task Groups" provide a means for applying task modifiers to groups of tasks. Once a Task is declared as part of a group task, modifiers like drop() or restartable() will no longer affect the individual Task. Instead those modifiers can be applied to the entire group.

import { task, taskGroup } from 'ember-concurrency';

export default Controller.extend({
  chores: taskGroup().drop(),

  mowLawn:       task(taskFn).group('chores'),
  doDishes:      task(taskFn).group('chores'),
  changeDiapers: task(taskFn).group('chores')
});
Source:
Returns:
Type
TaskGroup

timeout(ms)

Yielding timeout(ms) will pause a task for the duration of time passed in, in milliseconds.

The task below, when performed, will print a message to the console every second.

export default Component.extend({
  myTask: task(function * () {
    while (true) {
      console.log("Hello!");
      yield timeout(1000);
    }
  })
});
Parameters:
Name Type Description
ms number

the amount of time to sleep before resuming the task, in milliseconds

Source:

waitForEvent(object, eventName)

Use waitForEvent to pause the task until an event is fired. The event can either be a jQuery event or an Ember.Evented event (or any event system where the object supports .on() .one() and .off()).

import { task, waitForEvent } from 'ember-concurrency';
export default Component.extend({
  myTask: task(function * () {
    console.log("Please click anywhere..");
    let clickEvent = yield waitForEvent($('body'), 'click');
    console.log("Got event", clickEvent);

    let emberEvent = yield waitForEvent(this, 'foo');
    console.log("Got foo event", emberEvent);

    // somewhere else: component.trigger('foo', { value: 123 });
  })
});
Parameters:
Name Type Description
object object

the Ember Object or jQuery selector (with ,on(), .one(), and .off()) that the event fires from

eventName function

the name of the event to wait for

Source:

waitForProperty(object, key, callbackOrValue)

Use waitForProperty to pause the task until a property on an object changes to some expected value. This can be used for a variety of use cases, including synchronizing with another task by waiting for it to become idle, or change state in some other way. If you omit the callback, waitForProperty will resume execution when the observed property becomes truthy. If you provide a callback, it'll be called immediately with the observed property's current value, and multiple times thereafter whenever the property changes, until you return a truthy value from the callback, or the current task is canceled. You can also pass in a non-Function value in place of the callback, in which case the task will continue executing when the property's value becomes the value that you passed in.

import { task, waitForProperty } from 'ember-concurrency';
export default Component.extend({
  foo: 0,

  myTask: task(function * () {
    console.log("Waiting for `foo` to become 5");

    yield waitForProperty(this, 'foo', v => v === 5);
    // alternatively: yield waitForProperty(this, 'foo', 5);

    // somewhere else: this.set('foo', 5)

    console.log("`foo` is 5!");

    // wait for another task to be idle before running:
    yield waitForProperty(this, 'otherTask.isIdle');
    console.log("otherTask is idle!");
  })
});
Parameters:
Name Type Description
object object

an object (most likely an Ember Object)

key string

the property name that is observed for changes

callbackOrValue function

a Function that should return a truthy value when the task should continue executing, or a non-Function value that the watched property needs to equal before the task will continue running

Source:

waitForQueue(queueName)

Use waitForQueue to pause the task until a certain run loop queue is reached.

import { task, waitForQueue } from 'ember-concurrency';
export default Component.extend({
  myTask: task(function * () {
    yield waitForQueue('afterRender');
    console.log("now we're in the afterRender queue");
  })
});
Parameters:
Name Type Description
queueName string

the name of the Ember run loop queue

Source: