Async
Import :
const Async = brackets.getModule("utils/Async")
PromiseQueue
Kind: global class
new PromiseQueue()
Creates a queue of async operations that will be executed sequentially. Operations can be added to the queue at any time. If the queue is empty and nothing is currently executing when an operation is added, it will execute immediately. Otherwise, it will execute when the last operation currently in the queue has finished.
promiseQueue.add(op)
Adds an operation to the queue. If nothing is currently executing, it will execute immediately (and the next operation added to the queue will wait for it to complete). Otherwise, it will wait until the last operation in the queue (or the currently executing operation if nothing is in the queue) is finished. The operation must return a promise that will be resolved or rejected when it's finished; the queue will continue with the next operation regardless of whether the current operation's promise is resolved or rejected.
Kind: instance method of PromiseQueue
| Param | Type | Description |
|---|---|---|
| op | function | The operation to add to the queue. |
promiseQueue.removeAll()
Removes all pending promises from the queue.
Kind: instance method of PromiseQueue
ERROR_TIMEOUT : Object
Value passed to fail() handlers that have been triggered due to withTimeout()'s timeout
Kind: global variable
doInParallel(items, beginProcessItem, failFast) ⇒ $.Promise
Executes a series of tasks in parallel, returning a "master" Promise that is resolved once all the tasks have resolved. If one or more tasks fail, behavior depends on the failFast flag:
- If true, the master Promise is rejected as soon as the first task fails. The remaining tasks continue to completion in the background.
- If false, the master Promise is rejected after all tasks have completed.
If nothing fails: (M = master promise; 1-4 = tasks; d = done; F = fail) M ------------d 1 >---d . 2 >------d . 3 >---------d . 4 >------------d
With failFast = false: M ------------F 1 >---d . . 2 >------d . . 3 >---------F . 4 >------------d
With failFast = true: -- equivalent to $.when() M ---------F 1 >---d . 2 >------d . 3 >---------F 4 >------------d (#4 continues even though master Promise has failed) (Note: if tasks finish synchronously, the behavior is more like failFast=false because you won't get a chance to respond to the master Promise until after all items have been processed)
To perform task-specific work after an individual task completes, attach handlers to each Promise before beginProcessItem() returns it.
Note: don't use this if individual tasks (or their done/fail handlers) could ever show a user- visible dialog: because they run in parallel, you could show multiple dialogs atop each other.
Kind: global function
| Param | Type |
|---|---|
| items | Array.<*> |
| beginProcessItem | function |
| failFast | boolean |
doSequentially(items, beginProcessItem, failAndStopFast) ⇒ $.Promise
Executes a series of tasks in serial (task N does not begin until task N-1 has completed). Returns a "master" Promise that is resolved once all the tasks have resolved. If one or more tasks fail, behavior depends on the failAndStopFast flag:
- If true, the master Promise is rejected as soon as the first task fails. The remaining tasks are never started (the serial sequence is stopped).
- If false, the master Promise is rejected after all tasks have completed.
If nothing fails: M ------------d 1 >---d . 2 >--d . 3 >--d . 4 >--d
With failAndStopFast = false: M ------------F 1 >---d . . 2 >--d . . 3 >--F . 4 >--d
With failAndStopFast = true: M ---------F 1 >---d . 2 >--d . 3 >--F 4 (#4 never runs)
To perform task-specific work after an individual task completes, attach handlers to each Promise before beginProcessItem() returns it.
Kind: global function
| Param | Type |
|---|---|
| items | Array.<*> |
| beginProcessItem | function |
| failAndStopFast | boolean |
doSequentiallyInBackground(items, fnProcessItem, [maxBlockingTime], [idleTime]) ⇒ $.Promise
Executes a series of synchronous tasks sequentially spread over time-slices less than maxBlockingTime. Processing yields by idleTime between time-slices.
Kind: global function
| Param | Type | Description |
|---|---|---|
| items | Array.<*> | |
| fnProcessItem | function | Function that synchronously processes one item |
| [maxBlockingTime] | number | |
| [idleTime] | number |
firstSequentially(items, beginProcessItem) ⇒ $.Promise
Executes a series of tasks in serial (task N does not begin until task N-1 has completed). Returns a "master" Promise that is resolved when the first task has resolved. If all tasks fail, the master Promise is rejected.
Kind: global function
| Param | Type |
|---|---|
| items | Array.<*> |
| beginProcessItem | function |
doInParallel_aggregateErrors(items, beginProcessItem) ⇒ $.Promise
Executes a series of tasks in parallel, saving up error info from any that fail along the way. Returns a Promise that is only resolved/rejected once all tasks are complete. This is essentially a wrapper around doInParallel(..., false).
If one or more tasks failed, the entire "master" promise is rejected at the end - with one argument: an array objects, one per failed task. Each error object contains:
- item -- the entry in items whose task failed
- error -- the first argument passed to the fail() handler when the task failed
Kind: global function
| Param | Type |
|---|---|
| items | Array.<*> |
| beginProcessItem | function |
withTimeout(promise, timeout, [resolveTimeout]) ⇒ $.Promise
Adds timeout-driven termination to a Promise: returns a new Promise that is resolved/rejected when the given original Promise is resolved/rejected, OR is resolved/rejected after the given delay - whichever happens first.
If the original Promise is resolved/rejected first, done()/fail() handlers receive arguments piped from the original Promise. If the timeout occurs first instead, then resolve() or fail() (with Async.ERROR_TIMEOUT) is called based on value of resolveTimeout.
Kind: global function
| Param | Type | Description |
|---|---|---|
| promise | $.Promise | |
| timeout | number | |
| [resolveTimeout] | boolean | If true, then resolve deferred on timeout, otherwise reject. Default is false. |
waitForAll(promises, [failOnReject], [timeout]) ⇒ $.Promise
Allows waiting for all the promises to be either resolved or rejected. Unlike $.when(), it does not call .fail() or .always() handlers on first reject. The caller should take all the precaution to make sure all the promises passed to this function are completed to avoid blocking.
If failOnReject is set to true, promise returned by the function will be rejected if at least one of the promises was rejected. The default value is false, which will cause the call to this function to be always successfully resolved.
If timeout is specified, the promise will be rejected on timeout as per Async.withTimeout.
Kind: global function
Returns: $.Promise - A Promise which will be resolved once all dependent promises are resolved.
It is resolved with an array of results from the successfully resolved dependent promises.
The resulting array may not be in the same order or contain as many items as there were
promises to wait on and it will contain 'undefined' entries for those promises that resolve
without a result.
| Param | Type | Description |
|---|---|---|
| promises | Array.<$.Promise> | Array of promises to wait for |
| [failOnReject] | boolean | Whether to reject or not if one of the promises has been rejected. |
| [timeout] | number | Number of milliseconds to wait until rejecting the promise |
chain(functions, args) ⇒ jQuery.Promise
Chains a series of synchronous and asynchronous (jQuery promise-returning) functions together, using the result of each successive function as the argument(s) to the next. A promise is returned that resolves with the result of the final call if all calls resolve or return normally. Otherwise, if any of the functions reject or throw, the computation is halted immediately and the promise is rejected with this halting error.
Kind: global function
Returns: jQuery.Promise - A promise that resolves with the result of the final call, or
rejects with the first error.
| Param | Type | Description |
|---|---|---|
| functions | Array.<function(*)> | Functions to be chained |
| args | Array | Arguments to call the first function with |
promisify(obj, method, ...varargs) ⇒ $.Promise
Utility for converting a method that takes (error, callback) to one that returns a promise; useful for using FileSystem methods (or other Node-style API methods) in a promise-oriented workflow. For example, instead of
var deferred = new $.Deferred();
file.read(function (err, contents) {
if (err) {
deferred.reject(err);
} else {
// ...process the contents...
deferred.resolve();
}
}
return deferred.promise();
you can just do
return Async.promisify(file, "read").then(function (contents) );
The object/method are passed as an object/string pair so that we can properly call the method without the caller having to deal with "bind" all the time.
Kind: global function
Returns: $.Promise - A promise that is resolved with the arguments that were passed to the
errback (not including the err argument) if err is null, or rejected with the err if
non-null.
| Param | Type | Description |
|---|---|---|
| obj | Object | The object to call the method on. |
| method | string | The name of the method. The method should expect the errback as its last parameter. |
| ...varargs | Object | The arguments you would have normally passed to the method (excluding the errback itself). |