async.Deferred Extends
A Deferred represents the result of an asynchronous operation. A Deferred instance has no result when it is created, and is "fired" (given an initial result) by calling callback or errback. Once fired, the result is passed through a sequence of callback functions registered with addCallback or addErrback. The functions may mutate the result before it is passed to the next function in the sequence. Callbacks and errbacks may be added at any time, including after the Deferred has been "fired". If there are no pending actions in the execution sequence of a fired Deferred, any new callback functions will be called with the last computed result. Adding a callback function is the only way to access the result of the Deferred. If a Deferred operation is canceled, an optional user-provided cancellation function is invoked which may perform any special cleanup, followed by firing the Deferred's errback sequence with a CanceledError. If the Deferred has already fired, cancellation is ignored. Deferreds may be templated to a specific type they produce using generics with syntax such as: /** @type {goog.async.Deferred.} */ var d = new goog.async.Deferred(); // Compiler can infer that foo is a string. d.addCallback(function(foo) {...}); d.callback('string'); // Checked to be passed a string Since deferreds are often used to produce different values across a chain, the type information is not propagated across chains, but rather only associated with specifically cast objects.

Inheritance

Constructor

goog.async.Deferred(opt_onCancelFunctionopt_defaultScope)

Parameters

opt_onCancelFunction : Function=
A function that will be called if the Deferred is canceled. If provided, this function runs before the Deferred is fired with a CanceledError.
opt_defaultScope : Object=
The default object context to call callbacks and errbacks in.

Instance Methods

Public Protected Private
addBoth(fopt_scope) !goog.async.Deferred
Registers one function as both a callback and errback.
Arguments:
f : !?function(this:T,):?
The function to be called on any result.
opt_scope : T=
An optional scope to call the function in.
Returns: !goog.async.Deferred  This Deferred.
code »
addCallback(cbopt_scope) !goog.async.Deferred
Register a callback function to be called with a successful result. If no value is returned by the callback function, the result value is unchanged. If a new value is returned, it becomes the Deferred result and will be passed to the next callback in the execution sequence. If the function throws an error, the error becomes the new result and will be passed to the next errback in the execution chain. If the function returns a Deferred, the execution sequence will be blocked until that Deferred fires. Its result will be passed to the next callback (or errback if it is an error result) in this Deferred's execution sequence.
Arguments:
cb : !function(this:T,VALUE):?
The function to be called with a successful result.
opt_scope : T=
An optional scope to call the callback in.
Returns: !goog.async.Deferred  This Deferred.
code »
addCallbacks(cbebopt_scope) !goog.async.Deferred
Registers a callback function and an errback function at the same position in the execution sequence. Only one of these functions will execute, depending on the error state during the execution sequence. NOTE: This is not equivalent to def.addCallback().addErrback()! If the callback is invoked, the errback will be skipped, and vice versa.
Arguments:
cb : (function(this:T,VALUE):?) | null
The function to be called on a successful result.
eb : (?function(this:T,):?) | null
The function to be called on an unsuccessful result.
opt_scope : T=
An optional scope to call the functions in.
Returns: !goog.async.Deferred  This Deferred.
code »
addErrback(ebopt_scope) !goog.async.Deferred.<VALUE>
Register a callback function to be called with an error result. If no value is returned by the function, the error result is unchanged. If a new error value is returned or thrown, that error becomes the Deferred result and will be passed to the next errback in the execution sequence. If the errback function handles the error by returning a non-error value, that result will be passed to the next normal callback in the sequence. If the function returns a Deferred, the execution sequence will be blocked until that Deferred fires. Its result will be passed to the next callback (or errback if it is an error result) in this Deferred's execution sequence.
Arguments:
eb : !?function(this:T,):?
The function to be called on an unsuccessful result.
opt_scope : T=
An optional scope to call the errback in.
Returns: !goog.async.Deferred.<VALUE>  This Deferred.
code »
assertNotDeferred_(obj)
Asserts that an object is not a Deferred.
Arguments:
obj : *
The object to test.
code »
awaitDeferred(otherDeferred) !goog.async.Deferred
Makes this Deferred wait for another Deferred's execution sequence to complete before continuing. This is equivalent to adding a callback that returns otherDeferred, but doesn't prevent additional callbacks from being added to otherDeferred.
Arguments:
otherDeferred : !goog.async.Deferred | !goog.Thenable
The Deferred to wait for.
Returns: !goog.async.Deferred  This Deferred.
code »
branch(opt_propagateCancel) !goog.async.Deferred.<VALUE>
Creates a branch off this Deferred's execution sequence, and returns it as a new Deferred. The branched Deferred's starting result will be shared with the parent at the point of the branch, even if further callbacks are added to the parent. All branches at the same stage in the execution sequence will receive the same starting value.
Arguments:
opt_propagateCancel : boolean=
If cancel() is called on every child branch created with opt_propagateCancel, the parent will be canceled as well.
Returns: !goog.async.Deferred.<VALUE>  A Deferred that will be started with the computed result from this stage in the execution sequence.
code »
branchCancel_()
Handle a single branch being canceled. Once all branches are canceled, this Deferred will be canceled as well.
code »
callback(opt_result)
Fire the execution sequence for this Deferred by passing the starting result to the first registered callback.
Arguments:
opt_result : VALUE=
The starting result.
code »
cancel(opt_deepCancel)
Cancels a Deferred that has not yet been fired, or is blocked on another deferred operation. If this Deferred is waiting for a blocking Deferred to fire, the blocking Deferred will also be canceled. If this Deferred was created by calling branch() on a parent Deferred with opt_propagateCancel set to true, the parent may also be canceled. If opt_deepCancel is set, cancel() will be called on the parent (as well as any other ancestors if the parent is also a branch). If one or more branches were created with opt_propagateCancel set to true, the parent will be canceled if cancel() is called on all of those branches.
Arguments:
opt_deepCancel : boolean=
If true, cancels this Deferred's parent even if cancel() hasn't been called on some of the parent's branches. Has no effect on a branch without opt_propagateCancel set to true.
code »
chainDeferred(otherDeferred) !goog.async.Deferred
Links another Deferred to the end of this Deferred's execution sequence. The result of this execution sequence will be passed as the starting result for the chained Deferred, invoking either its first callback or errback.
Arguments:
otherDeferred : !goog.async.Deferred
The Deferred to chain.
Returns: !goog.async.Deferred  This Deferred.
code »
check_()
Verifies that the Deferred has not yet been fired.
code »
continue_(isSuccessres)
Called after a blocking Deferred fires. Unblocks this Deferred and resumes its execution sequence.
Arguments:
isSuccess : boolean
Whether the result is a success or an error.
res : *
The result of the blocking Deferred.
code »
errback(opt_result)
Fire the execution sequence for this Deferred by passing the starting error result to the first registered errback.
Arguments:
opt_result : *=
The starting error.
code »
fire_()
Exhausts the execution sequence while a result is available. The result may be modified by callbacks or errbacks, and execution will block if the returned result is an incomplete Deferred.
code »
hasErrback_() boolean
No description.
Returns: boolean  Whether an errback exists in the remaining sequence.
code »
hasFired() boolean
No description.
Returns: boolean  Whether the execution sequence has been started on this Deferred by invoking callback or errback.
code »
isError(res) boolean
No description.
Arguments:
res : *
The latest result in the execution sequence.
Returns: boolean  Whether the current result is an error that should cause the next errback to fire. May be overridden by subclasses to handle special error types.
code »
makeStackTraceLong_(error)
Attempt to make the error's stack trace be long in that it contains the stack trace from the point where the deferred was created on top of the current stack trace to give additional context.
Arguments:
error : *
No description.
code »
then()
Implements for seamless integration with . Deferred results are mutable and may represent multiple values over their lifetime. Calling then on a Deferred returns a Promise with the result of the Deferred at that point in its callback chain. Note that if the Deferred result is never mutated, and only then calls are made, the Deferred will behave like a Promise.
code »
updateResult_(isSuccessres)
Updates the current result based on the success or failure of the last action in the execution sequence.
Arguments:
isSuccess : boolean
Whether the new result is a success or an error.
res : *
The result.
code »

Instance Properties

blocked_ :
Whether the Deferred is blocked waiting on another Deferred to fire. If a callback or errback returns a Deferred as a result, the execution sequence is blocked until that Deferred result becomes available.
Code »
blocking_ :
Whether this Deferred is blocking execution of another Deferred. If this instance was returned as a result in another Deferred's execution sequence,that other Deferred becomes blocked until this instance's execution sequence completes. No additional callbacks may be added to a Deferred once it is blocking another instance.
Code »
branches_ :
The number of Deferred objects that have been branched off this one. This will be decremented whenever a branch is fired or canceled.
Code »
constructorStack_ :
Holds the stack trace at time of deferred creation if the JS engine provides the Error.captureStackTrace API.
Code »
defaultScope_ :
The default scope to execute callbacks and errbacks in.
Code »
fired_ :
Whether the Deferred has been fired.
Code »
hadError_ :
Whether the last result in the execution sequence was an error.
Code »
onCancelFunction_ :
Optional function that will be called if the Deferred is canceled.
Code »
If this Deferred was created by branch(), this will be the "parent" Deferred.
Code »
result_ :
The current Deferred result, updated as callbacks and errbacks are executed.
Code »
sequence_ :
Entries in the sequence are arrays containing a callback, an errback, and an optional scope. The callback or errback in an entry may be null.
Code »
silentlyCanceled_ :
Whether the Deferred has been canceled without having a custom cancel function.
Code »
unhandledErrorId_ :
If an error is thrown during Deferred execution with no errback to catch it, the error is rethrown after a timeout. Reporting the error after a timeout allows execution to continue in the calling context (empty when no error is scheduled).
Code »

Static Methods

goog.async.Deferred.assertNoErrors()
Asserts that there are no pending deferred errors. If there are any scheduled errors, one will be thrown immediately to make this function fail.
code »
goog.async.Deferred.canceled() !goog.async.Deferred
Creates a Deferred that has already been canceled.
Returns: !goog.async.Deferred  The new Deferred.
code »
goog.async.Deferred.fail(res) !goog.async.Deferred
Creates a Deferred that has an initial error result.
Arguments:
res : *
The error result.
Returns: !goog.async.Deferred  The new Deferred.
code »
goog.async.Deferred.fromPromise(promise) !goog.async.Deferred.<T>
Creates a Deferred that fires when the given promise resolves. Use only during migration to Promises.
Arguments:
promise : !goog.Promise.<T>
No description.
Returns: !goog.async.Deferred.<T>  The new Deferred.
code »
goog.async.Deferred.scheduleError_(error) number
Schedules an error to be thrown after a delay.
Arguments:
error : *
Error from a failing deferred.
Returns: number  Id of the error.
code »
goog.async.Deferred.succeed(opt_result) !goog.async.Deferred
Creates a Deferred that has an initial result.
Arguments:
opt_result : *=
The result.
Returns: !goog.async.Deferred  The new Deferred.
code »
goog.async.Deferred.unscheduleError_(id)
Unschedules an error from being thrown.
Arguments:
id : number
Id of the deferred error to unschedule.
code »
goog.async.Deferred.when(valuecallbackopt_scope) !goog.async.Deferred
Normalizes values that may or may not be Deferreds. If the input value is a Deferred, the Deferred is branched (so the original execution sequence is not modified) and the input callback added to the new branch. The branch is returned to the caller. If the input value is not a Deferred, the callback will be executed immediately and an already firing Deferred will be returned to the caller. In the following (contrived) example, if isImmediate is true then 3 is alerted immediately, otherwise 6 is alerted after a 2-second delay.
var value;
if (isImmediate) {
  value = 3;
} else {
  value = new goog.async.Deferred();
  setTimeout(function() { value.callback(6); }, 2000);
}

var d = goog.async.Deferred.when(value, alert);
Arguments:
value : *
Deferred or normal value to pass to the callback.
callback : !?function(this:T, ):?
The callback to execute.
opt_scope : T=
An optional scope to call the callback in.
Returns: !goog.async.Deferred  A new Deferred that will call the input callback with the input value.
code »

Static Properties

goog.async.Deferred.LONG_STACK_TRACES :
No description.
Code »
goog.async.Deferred.STRICT_ERRORS :
No description.
Code »
goog.async.Deferred.errorMap_ :
Map of unhandled errors scheduled to be rethrown in a future timestep.
Code »

Package async

Package Reference