Global

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.

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

Yielding forever will pause a task indefinitely until it is cancelled (i.e. via host object destruction, the restartable modifier, or manual cancellation).

This is often useful in cases involving animation: if you're using Liquid Fire, or some other animation scheme, sometimes you'll notice buttons visibly reverting to their inactive states during a route transition. By yielding forever in a Component task that drives a button's active state, you can keep a task indefinitely running until the animation runs to completion.

NOTE: Liquid Fire also includes a useful waitUntilIdle() method on the liquid-fire-transitions service that you can use in a lot of these cases, but it won't cover cases of asynchrony that are unrelated to animation, in which case forever might be better suited to your needs.

import { task, forever } from 'ember-concurrency';
export default class MyComponent extends Component {
  @service myService;
  myTask = task(async () => {
    await this.myService.doSomethingThatCausesATransition();
    await forever;
  });
}

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 hash will be canceled
• if any of the items rejects/cancels, all other cancelable items (e.g. TaskInstances) will be canceled

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

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

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

Yielding animationFrame() will pause a task until after the next animation frame using the native requestAnimationFrame() browser API.

The task below, when performed, will print the time since the last loop run for every animation frame.

export default class MyComponent extends Component {
  myTask = task(async () => {
    let lastNow = performance.now();
    while (true) {
      await animationFrame();

      let now = performance.now();
      let dt = now - lastNow;
      lastNow = now;

      console.log(dt);
    }
  });
}

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.myTask.perform().catch(e => {
    if (!didCancel(e)) { throw e; }
  });
}

Returns a specified modifier, if it exists in the registry

Returns whether a specified modifier exists in the registry

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

The timeout will use the native setTimeout() browser API, instead of the Ember runloop, which means that test helpers will not wait for it to complete.

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

export default class MyComponent extends Component {
  myTask = task(async () => {
    while (true) {
      console.log("Hello!");
      await rawTimeout(1000);
    }
  });
}

Registers a new modifier with the modifier registry

A Task is a cancelable, restartable, asynchronous operation that is driven by an async 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 an async arrow function, which will be invoked when the task is performed. Async functions with the await keyword can be used to elegantly express asynchronous, cancelable operations.

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 Component from '@glimmer/component';
import { task, timeout } from 'ember-concurrency';

export default class MyComponent extends Component {
  myTask = task(async () => {
    console.log("Pausing for a second...");
    await 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.

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

This timeout will be scheduled on the Ember runloop, which means that test helpers will wait for it to complete before continuing with the test. See rawTimeout() if you need different behavior.

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

export default class MyComponent extends Component {
  myTask = task(async () => {
    while (true) {
      console.log("Hello!");
      await timeout(1000);
    }
  });
}

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 class MyComponent extends Component {
  myTask = task(async () => {
    console.log("Please click anywhere..");
    let clickEvent = await waitForEvent($('body'), 'click');
    console.log("Got event", clickEvent);

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

    // somewhere else: component.trigger('foo', { value: 123 });
  });
}

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 class MyComponent extends Component {
  @tracked foo = 0;

  myTask = task(async () => {
    console.log("Waiting for `foo` to become 5");

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

    // somewhere else: this.foo = 5;

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

    // wait for another task to be idle before running:
    await waitForProperty(this, 'otherTask.isIdle');
    console.log("otherTask is idle!");
  });
}

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

import { task, waitForQueue } from 'ember-concurrency';
export default class MyComponent extends Component {
  myTask = task(async () => {
    await waitForQueue('afterRender');
    console.log("now we're in the afterRender queue");
  });
}