[FIX] async docs
bzr revid: xmo@openerp.com-20121112073957-loeg9j4vbofklpnb
This commit is contained in:
parent
140f647167
commit
0074bc4b3d
|
@ -43,8 +43,8 @@ directly to asynchronous methods is the ability to :ref:`compose them
|
||||||
Using deferreds
|
Using deferreds
|
||||||
~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
deferreds have only one method of importance: :js:func:`Deferred.then`. This
|
Deferreds's most important method is :js:func:`Deferred.then`. It is
|
||||||
method is used to attach new callbacks to the deferred object.
|
used to attach new callbacks to the deferred object.
|
||||||
|
|
||||||
* the first parameter attaches a success callback, called when the
|
* the first parameter attaches a success callback, called when the
|
||||||
deferred object is successfully resolved and provided with the
|
deferred object is successfully resolved and provided with the
|
||||||
|
@ -176,9 +176,9 @@ Deferred chaining
|
||||||
|
|
||||||
A second useful composition is starting an asynchronous operation as
|
A second useful composition is starting an asynchronous operation as
|
||||||
the result of an other asynchronous operation, and wanting the result
|
the result of an other asynchronous operation, and wanting the result
|
||||||
of both: :js:func:`Deferred.then` returns the deferred on which it was
|
of both: with the tools described so far, handling e.g. OpenERP's
|
||||||
called, so handle e.g. OpenERP's search/read sequence with this would
|
search/read sequence with this would require something along the lines
|
||||||
require something along the lines of:
|
of:
|
||||||
|
|
||||||
.. code-block:: javascript
|
.. code-block:: javascript
|
||||||
|
|
||||||
|
@ -193,21 +193,14 @@ require something along the lines of:
|
||||||
While it doesn't look too bad for trivial code, this quickly gets
|
While it doesn't look too bad for trivial code, this quickly gets
|
||||||
unwieldy.
|
unwieldy.
|
||||||
|
|
||||||
Instead, jQuery provides a tool to handle this kind of chains:
|
But :js:func:`~Deferred.then` also allows handling this kind of
|
||||||
:js:func:`Deferred.pipe`.
|
chains: it returns a new promise object, not the one it was called
|
||||||
|
with, and the return values of the callbacks is actually important to
|
||||||
:js:func:`~Deferred.pipe` has the same signature as
|
it: whichever callback is called,
|
||||||
:js:func:`~Deferred.then` and could be used in the same manner
|
|
||||||
provided its return value was not used.
|
|
||||||
|
|
||||||
It differs from :js:func:`~Deferred.then` in two ways: it returns a
|
|
||||||
new promise object, not the one it was called with, and the return
|
|
||||||
values of the callbacks is actually important to it: whichever
|
|
||||||
callback is called,
|
|
||||||
|
|
||||||
* If the callback is not set (not provided or left to null), the
|
* If the callback is not set (not provided or left to null), the
|
||||||
resolution or rejection value(s) is simply forwarded to
|
resolution or rejection value(s) is simply forwarded to
|
||||||
:js:func:`~Deferred.pipe`'s promise (it's essentially a noop)
|
:js:func:`~Deferred.then`'s promise (it's essentially a noop)
|
||||||
|
|
||||||
* If the callback is set and does not return an observable object (a
|
* If the callback is set and does not return an observable object (a
|
||||||
deferred or a promise), the value it returns (``undefined`` if it
|
deferred or a promise), the value it returns (``undefined`` if it
|
||||||
|
@ -215,7 +208,7 @@ callback is called,
|
||||||
|
|
||||||
.. code-block:: javascript
|
.. code-block:: javascript
|
||||||
|
|
||||||
promise.pipe(function () {
|
promise.then(function () {
|
||||||
console.log('called');
|
console.log('called');
|
||||||
});
|
});
|
||||||
|
|
||||||
|
@ -232,7 +225,7 @@ callback is called,
|
||||||
|
|
||||||
.. code-block:: javascript
|
.. code-block:: javascript
|
||||||
|
|
||||||
return Model.search(condition).pipe(function (ids) {
|
return Model.search(condition).then(function (ids) {
|
||||||
return Model.read(ids, fields);
|
return Model.read(ids, fields);
|
||||||
});
|
});
|
||||||
|
|
||||||
|
@ -241,10 +234,10 @@ callback is called,
|
||||||
will be resolved with ``read``'s resolution values if the chain
|
will be resolved with ``read``'s resolution values if the chain
|
||||||
executes correctly.
|
executes correctly.
|
||||||
|
|
||||||
:js:func:`~Deferred.pipe` is also useful to adapt third-party
|
:js:func:`~Deferred.then` is also useful to adapt third-party
|
||||||
promise-based APIs, in order to filter their resolution value counts
|
promise-based APIs, in order to filter their resolution value counts
|
||||||
for instance (to take advantage of :js:func:`when` 's special treatment
|
for instance (to take advantage of :js:func:`when` 's special
|
||||||
of single-value promises).
|
treatment of single-value promises).
|
||||||
|
|
||||||
|
|
||||||
.. _promises: http://en.wikipedia.org/wiki/Promise_(programming)
|
.. _promises: http://en.wikipedia.org/wiki/Promise_(programming)
|
||||||
|
|
Loading…
Reference in New Issue