class Sqimitive.Async
extends Sqimitive.Base
Defined in: sqimitive-async.js, line 43
The maximum number (absolute, i.e. positive) accepted by whenComplete() and others; out of range priority is clamped to the nearest value.
-Infinity
and Infinity
to specify minimum and maximum priority.
// This function is called before listeners to 'success' with a larger
// priority (which is 0 by default).
async.whenSuccess(function (async) { ... }, this, -Infinity)
Defined in: sqimitive-async.js, line 188 • Show code
MAX_PRIORITY: 2,
Modifiers: protected
New standard options (Base._opt):
Name | Types | Notes |
---|---|---|
status | operation null not started or not finished | Reflects both this instance’s own status and status of its children. When an operation wrapped by this Async finishes and assuming it has
no _children, set() |
true operation succeeded | ||
false operation failed | ||
ignoreError | bool | If set, this instance will be considered succeeded
by isSuccessful() even if status is false Don’t change this value when this instance is no longer isLoading() because the expected handlers won’t be called:
|
Defined in: sqimitive-async.js, lines 223-226 (4 lines) • Show code
_opt: {
status: null,
ignoreError: false,
},
Aborts the operation of this instance.
async.sink('abort')
The default implementation does nothing (is a stub).
Defined in: sqimitive-async.js, line 607
Prepares this instance for new use.
It’s recommended to create a new Async instance for every new batch of tasks. However, clear() may improve performance when thousands of objects need to be created but some could be reused.
Removes event listeners for success/error/complete (but not for
exception), calls abort() on self and on _children
(non-recursively), calls Base.remove() on children and sets status
(_opt) to null
(isLoading()).
Defined in: sqimitive-async.js, lines 469-476 (8 lines) • Show code
clear: function () {
_.each(['success', 'error', 'complete'], function (e) { this.off(e) }, this)
this.abort()
this.invoke('abort')
this.invoke('remove')
this.set('status', null)
return this
},
Called when this instance stops being isLoading().
from sec
success, error and complete are called when this and nested operations have finished (resources loaded, etc.). Consider this analogy with exception handling:
try {
... // Async.success()
} catch (exception) {
... // Async.error()
} finally {
... // Async.complete()
}
But note that “real” exceptions thrown by listeners are handled by exception() outside of the normal pipeline (error’s are expected conditions, exceptions are not).
Each handler is called at most once as if it was bound with once(). If
a handler changes the status
_opt, others are skipped and events are
re-fired.
var async = new MyAsync({...})
// If async is already complete before we call on() - our handler will
// not be triggered:
async.on('success', function (async) { ... })
// So you want to do this:
async.whenSuccess(function (async) { ... })
The call order of handlers is deterministic (Async’s nest() acts as
on() because of _childEvents/_forward()) but it’s usually more
convenient to use specific priority levels to not depend on the order of
nest()/on() calls: on('success')
is guaranteed to be called
after success-3
but before success2
.
Defined in: sqimitive-async.js, line 562
Sets the status
_opt to true
if have no _children and is still
isLoading().
Types | Notes |
---|---|
undefined if not empty or is not loading | |
true |
_.each(filesToLoad, function (url) {
async.nest(new MyAsync({src: url}))
})
async.whenComplete(allLoaded)
async.doneIfEmpty()
//=> true
// if there were no filesToLoad then mark async as complete right
// away
async.doneIfEmpty()
//=> undefined - already complete, call ignored
Defined in: sqimitive-async.js, lines 452-457 (6 lines) • Show code
doneIfEmpty: function () {
if (!this.length && this.isLoading()) {
this.set('status', true)
return true
}
},
Called when this instance or one of its children has failed.
By default, Async doesn’t store any error information because it is operation-agnostic; you may use _opt for this.
from sec
success, error and complete are called when this and nested operations have finished (resources loaded, etc.). Consider this analogy with exception handling:
try {
... // Async.success()
} catch (exception) {
... // Async.error()
} finally {
... // Async.complete()
}
But note that “real” exceptions thrown by listeners are handled by exception() outside of the normal pipeline (error’s are expected conditions, exceptions are not).
Each handler is called at most once as if it was bound with once(). If
a handler changes the status
_opt, others are skipped and events are
re-fired.
var async = new MyAsync({...})
// If async is already complete before we call on() - our handler will
// not be triggered:
async.on('success', function (async) { ... })
// So you want to do this:
async.whenSuccess(function (async) { ... })
The call order of handlers is deterministic (Async’s nest() acts as
on() because of _childEvents/_forward()) but it’s usually more
convenient to use specific priority levels to not depend on the order of
nest()/on() calls: on('success')
is guaranteed to be called
after success-3
but before success2
.
Defined in: sqimitive-async.js, line 552
Called when an exception was thrown during success, error or complete.
async.on('exception', e => console.error(e.message))
In contrast with JavaScript’s Promise
an error in handling the
“promise” (Async) doesn’t mark that promise failed if its underlying
action (e.g. an AJAX call) has succeeded.
If an exception is thrown during an error or success handlers then remaining handlers are skipped, complete is triggered and the exception is re-thrown. An exception during complete also skips remaining handlers of complete and is re-thrown unless there was an exception during error or success.
Other notes:
status
is stored in _opt). Only future exceptions can
be listened to, with the usual on().this
as an argument.Defined in: sqimitive-async.js, lines 603-605 (3 lines) • Show code
exception: function (e) {
throw e
},
Types | Notes |
---|---|
true when still loading (status _opt is null ) | |
false when failed or succeeded (isSuccessful) |
Defined in: sqimitive-async.js, lines 502-504 (3 lines) • Show code
isLoading: function () {
return this.get('status') == null
},
Types | Notes |
---|---|
null when still isLoading() | |
true if status _opt is true or ignoreError _opt is set | |
false |
ignoreError
affects all methods using isSuccessful(), in particular
whenSuccess() and whenError():
async.set('status', false) // fail it
async.isSuccessful() //=> false
async.set('ignoreError', true)
async.isSuccessful() //=> true
async.whenSuccess(() => alert('fired!'))
// alerts
However, changing ignoreError
on run-time is not recommended – see
_opt.
Defined in: sqimitive-async.js, lines 495-498 (4 lines) • Show code
isSuccessful: function () {
var s = this.get('status')
return s == null ? null : !!(this.get('ignoreError') || s)
},
Called when this instance and children have succeeded.
secsuccess, error and complete are called when this and nested operations have finished (resources loaded, etc.). Consider this analogy with exception handling:
try {
... // Async.success()
} catch (exception) {
... // Async.error()
} finally {
... // Async.complete()
}
But note that “real” exceptions thrown by listeners are handled by exception() outside of the normal pipeline (error’s are expected conditions, exceptions are not).
Each handler is called at most once as if it was bound with once(). If
a handler changes the status
_opt, others are skipped and events are
re-fired.
var async = new MyAsync({...})
// If async is already complete before we call on() - our handler will
// not be triggered:
async.on('success', function (async) { ... })
// So you want to do this:
async.whenSuccess(function (async) { ... })
The call order of handlers is deterministic (Async’s nest() acts as
on() because of _childEvents/_forward()) but it’s usually more
convenient to use specific priority levels to not depend on the order of
nest()/on() calls: on('success')
is guaranteed to be called
after success-3
but before success2
.
Defined in: sqimitive-async.js, line 506
Returns a debugger-friendly summary of this object:
The.Class.Name [length] ~¹ STATUS²
¹ ~
is output if the ignoreError
_opt is set.
² STATUS
is either “LOADING”, “DONE” or “ERROR”
For example:
AsyncImage [2] DONE
Defined in: sqimitive-async.js, line 268
Fire func
whenever this instance stops being isLoading() – see
complete.
$('#spinner').show()
var async = new MyAsync({...})
async.whenComplete(function (async) {
$('#spinner').hide()
})
// As if:
$('#spinner').show()
try {
do_async()
} finally {
$('#spinner').hide()
}
completeDescUnlike with a simple on('event')
(on()) func
gets called
immediately if the condition is already met (then priority
is
ignored). Otherwise, func
is executed before all handlers registered
with a larger priority
, among (in any order) those with the same and
after those with a lower. The value is clamped to the MAX_PRIORITY
range. In any case, func
is given this
(the Async instance).
Warning: the following is incorrect use because func
may be called
immediately, before the result is assigned to req
:
var req = (new Sqimitive.Async).whenComplete(function () {
// WRONG: req may be undefined:
req.foo()
})
// CORRECT: assign to the variable first:
var req = new Sqimitive.Async
req.whenComplete(function () { ... })
// CORRECT: or use the passed "this":
;(new Sqimitive.Async)
.whenComplete(function (req) { ... })
Defined in: sqimitive-async.js, lines 403-405 (3 lines) • Show code
whenComplete: function (func, cx, priority) {
return this._when(func, cx, priority, !this.isLoading(), 'complete')
},
Fire func
whenever this instance’s operation has failed – see error.
async.whenError(function (async) {
alert("Met an error :'(")
})
from completeDesc
Unlike with a simple on('event')
(on()) func
gets called
immediately if the condition is already met (then priority
is
ignored). Otherwise, func
is executed before all handlers registered
with a larger priority
, among (in any order) those with the same and
after those with a lower. The value is clamped to the MAX_PRIORITY
range. In any case, func
is given this
(the Async instance).
Warning: the following is incorrect use because func
may be called
immediately, before the result is assigned to req
:
var req = (new Sqimitive.Async).whenComplete(function () {
// WRONG: req may be undefined:
req.foo()
})
// CORRECT: assign to the variable first:
var req = new Sqimitive.Async
req.whenComplete(function () { ... })
// CORRECT: or use the passed "this":
;(new Sqimitive.Async)
.whenComplete(function (req) { ... })
Defined in: sqimitive-async.js, lines 416-418 (3 lines) • Show code
whenError: function (func, cx, priority) {
return this._when(func, cx, priority, this.isSuccessful() == false, 'error')
},
Fire func
whenever this instance’s operation has succeeded – see
success.
async.whenSuccess(app.start)
from completeDesc
Unlike with a simple on('event')
(on()) func
gets called
immediately if the condition is already met (then priority
is
ignored). Otherwise, func
is executed before all handlers registered
with a larger priority
, among (in any order) those with the same and
after those with a lower. The value is clamped to the MAX_PRIORITY
range. In any case, func
is given this
(the Async instance).
Warning: the following is incorrect use because func
may be called
immediately, before the result is assigned to req
:
var req = (new Sqimitive.Async).whenComplete(function () {
// WRONG: req may be undefined:
req.foo()
})
// CORRECT: assign to the variable first:
var req = new Sqimitive.Async
req.whenComplete(function () { ... })
// CORRECT: or use the passed "this":
;(new Sqimitive.Async)
.whenComplete(function (req) { ... })
Defined in: sqimitive-async.js, lines 428-430 (3 lines) • Show code
whenSuccess: function (func, cx, priority) {
return this._when(func, cx, priority, this.isSuccessful() == true, 'success')
},