Class: TaskInstance

TaskInstance

new TaskInstance()

A TaskInstance represent a single execution of a Task. Every call to Task#perform returns a TaskInstance.

TaskInstances are cancelable, either explicitly via TaskInstance#cancel or Task#cancelAll, or automatically due to the host object being destroyed, or because concurrency policy enforced by a Task Modifier canceled the task instance.

Source:

Members

(readonly) error

If this TaskInstance is canceled or throws an error (or yields a promise that rejects), this property will be set with that error. Otherwise, it is null.

Source:

(readonly) hasStarted

True if the task instance has started, else false.

Source:

(readonly) isCanceled

True if the task instance was canceled before it could run to completion.

Source:

(readonly) isDropped

True if the TaskInstance was canceled before it could ever start running. For example, calling .perform() twice on a task with the .drop() modifier applied will result in the second task instance being dropped.

Source:

(readonly) isError

True if the task instance resolves to a rejection.

Source:

(readonly) isFinished

True if the task has run to completion.

Source:

(readonly) isRunning

True if the task is still running.

Source:

(readonly) isSuccessful

True if the task instance is fulfilled.

Source:

(readonly) state

Describes the state that the task instance is in. Can be used for debugging, or potentially driving some UI state. Possible values are:

  • "dropped": task instance was canceled before it started
  • "canceled": task instance was canceled before it could finish
  • "finished": task instance ran to completion (even if an exception was thrown)
  • "running": task instance is currently running (returns true even if is paused on a yielded promise)
  • "waiting": task instance hasn't begun running yet (usually because the task is using the .enqueue() task modifier)

The animated timeline examples on the Task Concurrency docs page make use of this property.

Source:

(readonly) value

If this TaskInstance runs to completion by returning a property other than a rejecting promise, this property will be set with that value.

Source:

Methods

cancel()

Cancels the task instance. Has no effect if the task instance has already been canceled or has already finished running.

Source:

catch() → {Promise}

Source:
Returns:
Type
Promise

finally() → {Promise}

Source:
Returns:
Type
Promise

then() → {Promise}

Returns a promise that resolves with the value returned from the task's (generator) function, or rejects with either the exception thrown from the task function, or an error with a .name property with value "TaskCancelation".

Source:
Returns:
Type
Promise

Events

TASK_NAME:canceled

Event emitted when a TaskInstance is canceled.

on from @ember/object/evented may be used to create a binding on the host object to the event.

export default Ember.Component.extend({
  doSomething: task(function * () {
    // ... does something
  }),

  onDoSomethingCanceled: on('doSomething:canceled', function (taskInstance, cancelationReason) {
    // ...
  })
});
Parameters:
Name Type Description
taskInstance TaskInstance

Task instance that was started

cancelationReason string

Cancelation reason that was was provided to TaskInstance#cancel

Source:

TASK_NAME:errored

Event emitted when a TaskInstance throws an an error that is not handled within the task itself.

on from @ember/object/evented may be used to create a binding on the host object to the event.

export default Ember.Component.extend({
  doSomething: task(function * () {
    // ... does something
  }),

  onDoSomethingErrored: on('doSomething:errored', function (taskInstance, error) {
    // ...
  })
});
Parameters:
Name Type Description
taskInstance TaskInstance

Task instance that was started

error Error

Error that was thrown by the task instance

Source:

TASK_NAME:started

Event emitted when a new TaskInstance starts executing.

on from @ember/object/evented may be used to create a binding on the host object to the event.

export default Ember.Component.extend({
  doSomething: task(function * () {
    // ... does something
  }),

  onDoSomethingStarted: on('doSomething:started', function (taskInstance) {
    // ...
  })
});
Parameters:
Name Type Description
taskInstance TaskInstance

Task instance that was started

Source:

TASK_NAME:succeeded

Event emitted when a TaskInstance succeeds.

on from @ember/object/evented may be used to create a binding on the host object to the event.

export default Ember.Component.extend({
  doSomething: task(function * () {
    // ... does something
  }),

  onDoSomethingSucceeded: on('doSomething:succeeded', function (taskInstance) {
    // ...
  })
});
Parameters:
Name Type Description
taskInstance TaskInstance

Task instance that was succeeded

Source: