60 lines
1.9 KiB
ReStructuredText
60 lines
1.9 KiB
ReStructuredText
.. -*- restructuredtext -*-
|
|
|
|
In jQuery 1.5, jQuery has introduced a Deferred object in order to
|
|
better handle callbacks.
|
|
|
|
Along with Deferred, it introduced ``jQuery.when`` which allows, among
|
|
other things, for multiplexing deferreds (waiting on multiple
|
|
deferreds at the same time).
|
|
|
|
While this is very nice if all deferreds are available at the same
|
|
point, it doesn't really work if the resolution of a deferred can
|
|
generate more deferreds, or for collections of deferreds coming from
|
|
multiple sources (which may not be aware of one another).
|
|
|
|
Deferred.queue tries to be a solution to this. It is based on the
|
|
principle of FIFO multiple-producers multiple-consumers tasks queues,
|
|
such as Python's `queue.Queue`_. Any code with a reference to the
|
|
queue can add a promise to the queue, and the queue (which is a
|
|
promise itself) will only be resolved once all promises within are
|
|
resolved.
|
|
|
|
Quickstart
|
|
----------
|
|
|
|
Deferred.queue has a very simple life cycle: it is dormant when
|
|
created, it starts working as soon as promises get added to it (via
|
|
``.push``, or by providing them directly to its constructor), and as
|
|
soon as the last promise in the queue is resolved it resolves itself.
|
|
|
|
If any promise in the queue fails, the queue itself will be rejected
|
|
(without waiting for further promises).
|
|
|
|
Once a queue has been resolved or rejected, adding new promises to it
|
|
results in an error.
|
|
|
|
API
|
|
---
|
|
|
|
``jQuery.Deferred.queue([promises...])``
|
|
Creates a new deferred queue. Can be primed with a series of promise
|
|
objects.
|
|
|
|
``.push(promise...)``
|
|
Adds promises to the queue. Returns the queue itself (can be
|
|
chained).
|
|
|
|
If the queue has already been resolved or rejected, raises an error.
|
|
|
|
``.then([doneCallbacks][, failCallbacks])``
|
|
Promise/A ``then`` method.
|
|
|
|
``.done(doneCallbacks)``
|
|
jQuery ``done`` extension to promise objects
|
|
|
|
``.fail(failCallbacks)``
|
|
jQuery ``fail`` extension to promise objects
|
|
|
|
.. _queue.Queue:
|
|
http://docs.python.org/dev/library/queue.html
|