1 Don't stop the world now: asynchronous development and Javascript
2 =================================================================
4 As a language (and runtime), javascript is fundamentally
5 single-threaded. This means any blocking request or computation will
6 blocks the whole page (and, in older browsers, the software itself
7 even preventing users from switching to an other tab): a javascript
8 environment can be seen as an event-based runloop where application
9 developers have no control over the runloop itself.
11 As a result, performing long-running synchronous network requests or
12 other types of complex and expensive accesses is frowned upon and
13 asynchronous APIs are used instead.
15 Asynchronous code rarely comes naturally, especially for developers
16 used to synchronous server-side code (in Python, Java or C#) where the
17 code will just block until the deed is gone. This is increased further
18 when asynchronous programming is not a first-class concept and is
19 instead implemented on top of callbacks-based programming, which is
20 the case in javascript.
22 The goal of this guide is to provide some tools to deal with
23 asynchronous systems, and warn against systematic issues or dangers.
28 Deferreds are a form of `promises`_. OpenERP Web currently uses
29 `jQuery's deferred`_, but any `CommonJS Promises/A`_ implementation
32 The core idea of deferreds is that potentially asynchronous methods
33 will return a :js:class:`Deferred` object instead of an arbitrary
34 value or (most commonly) nothing.
36 This object can then be used to track the end of the asynchronous
37 operation by adding callbacks onto it, either success callbacks or
40 A great advantage of deferreds over simply passing callback functions
41 directly to asynchronous methods is the ability to :ref:`compose them
42 <deferred-composition>`.
47 `CommonJS Promises/A`_ deferreds have only one method of importance:
48 :js:func:`Deferred.then`. This method is used to attach new callbacks
49 to the deferred object.
51 * the first parameter attaches a success callback, called when the
52 deferred object is successfully resolved and provided with the
53 resolved value(s) for the asynchronous operation.
55 * the second parameter attaches a failure callback, called when the
56 deferred object is rejected and provided with rejection values
57 (often some sort of error message).
59 Callbacks attached to deferreds are never "lost": if a callback is
60 attached to an already resolved or rejected deferred, the callback
61 will be called (or ignored) immediately. A deferred is also only ever
62 resolved or rejected once, and is either resolved or rejected: a given
63 deferred can not call a single success callback twice, or call both a
64 success and a failure callbacks.
66 :js:func:`~Deferred.then` should be the method you'll use most often
67 when interacting with deferred objects (and thus asynchronous APIs).
72 After using asynchronous APIs may come the time to build them: for
73 `mocks`_, to compose deferreds from multiple source in a complex
74 manner, in order to let the current operations repaint the screen or
75 give other events the time to unfold, ...
77 This is easy using jQuery's deferred objects.
79 .. note:: this section is an implementation detail of jQuery Deferred
80 objects, the creation of promises is not part of any
81 standard (even tentative) that I know of. If you are using
82 deferred objects which are not jQuery's, their API may (and
83 often will) be completely different.
85 Deferreds are created by invoking their constructor [#]_ without any
86 argument. This creates a :js:class:`Deferred` instance object with the
89 :js:func:`Deferred.resolve`
91 As its name indicates, this method moves the deferred to the
92 "Resolved" state. It can be provided as many arguments as
93 necessary, these arguments will be provided to any pending success
96 :js:func:`Deferred.reject`
98 Similar to :js:func:`~Deferred.resolve`, but moves the deferred to
99 the "Rejected" state and calls pending failure handlers.
101 :js:func:`Deferred.promise`
103 Creates a readonly view of the deferred object. It is generally a
104 good idea to return a promise view of the deferred to prevent
105 callers from resolving or rejecting the deferred in your stead.
107 :js:func:`~Deferred.reject` and :js:func:`~Deferred.resolve` are used
108 to inform callers that the asynchronous operation has failed (or
109 succeeded). These methods should simply be called when the
110 asynchronous operation has ended, to notify anybody interested in its
113 .. _deferred-composition:
118 What we've seen so far is pretty nice, but mostly doable by passing
119 functions to other functions (well adding functions post-facto would
120 probably be a chore... still, doable).
122 Deferreds truly shine when code needs to compose asynchronous
123 operations in some way or other, as they can be used as a basis for
126 There are two main forms of compositions over deferred: multiplexing
127 and piping/cascading.
129 Deferred multiplexing
130 `````````````````````
132 The most common reason for multiplexing deferred is simply performing
133 2+ asynchronous operations and wanting to wait until all of them are
134 done before moving on (and executing more stuff).
136 The jQuery multiplexing function for promises is :js:func:`when`.
138 .. note:: the multiplexing behavior of jQuery's :js:func:`when` is an
139 (incompatible, mostly) extension of the behavior defined in
140 `CommonJS Promises/B`_.
142 This function can take any number of promises [#]_ and will return a
145 This returned promise will be resolved when *all* multiplexed promises
146 are resolved, and will be rejected as soon as one of the multiplexed
147 promises is rejected (it behaves like Python's ``all()``, but with
148 promise objects instead of boolean-ish).
150 The resolved values of the various promises multiplexed via
151 :js:func:`when` are mapped to the arguments of :js:func:`when`'s
152 success callback, if they are needed. The resolved values of a promise
153 are at the same index in the callback's arguments as the promise in
154 the :js:func:`when` call so you will have:
156 .. code-block:: javascript
158 $.when(p0, p1, p2, p3).then(
159 function (results0, results1, results2, results3) {
165 in a normal mapping, each parameter to the callback would be an
166 array: each promise is conceptually resolved with an array of 0..n
167 values and these values are passed to :js:func:`when`'s
168 callback. But jQuery treats deferreds resolving a single value
169 specially, and "unwraps" that value.
171 For instance, in the code block above if the index of each promise
172 is the number of values it resolves (0 to 3), ``results0`` is an
173 empty array, ``results2`` is an array of 2 elements (a pair) but
174 ``results1`` is the actual value resolved by ``p1``, not an array.
179 A second useful composition is starting an asynchronous operation as
180 the result of an other asynchronous operation, and wanting the result
181 of both: :js:func:`Deferred.then` returns the deferred on which it was
182 called, so handle e.g. OpenERP's search/read sequence with this would
183 require something along the lines of:
185 .. code-block:: javascript
187 var result = $.Deferred();
188 Model.search(condition).then(function (ids) {
189 Model.read(ids, fields).then(function (records) {
190 result.resolve(records);
193 return result.promise();
195 While it doesn't look too bad for trivial code, this quickly gets
198 Instead, jQuery provides a tool to handle this kind of chains:
199 :js:func:`Deferred.pipe`.
201 :js:func:`~Deferred.pipe` has the same signature as
202 :js:func:`~Deferred.then` and could be used in the same manner
203 provided its return value was not used.
205 It differs from :js:func:`~Deferred.then` in two ways: it returns a
206 new promise object, not the one it was called with, and the return
207 values of the callbacks is actually important to it: whichever
210 * If the callback is not set (not provided or left to null), the
211 resolution or rejection value(s) is simply forwarded to
212 :js:func:`~Deferred.pipe`'s promise (it's essentially a noop)
214 * If the callback is set and does not return an observable object (a
215 deferred or a promise), the value it returns (``undefined`` if it
216 does not return anything) will replace the value it was given, e.g.
218 .. code-block:: javascript
220 promise.pipe(function () {
221 console.log('called');
224 will resolve with the sole value ``undefined``.
226 * If the callback is set and returns an observable object, that object
227 will be the actual resolution (and result) of the pipe. This means a
228 resolved promise from the failure callback will resolve the pipe,
229 and a failure promise from the success callback will reject the
232 This provides an easy way to chain operation successes, and the
233 previous piece of code can now be rewritten:
235 .. code-block:: javascript
237 return Model.search(condition).pipe(function (ids) {
238 return Model.read(ids, fields);
241 the result of the whole expression will encode failure if either
242 ``search`` or ``read`` fails (with the right rejection values), and
243 will be resolved with ``read``'s resolution values if the chain
246 :js:func:`~Deferred.pipe` is also useful to adapt third-party
247 promise-based APIs, in order to filter their resolution value counts
248 for instance (to take advantage of :js:func:`when` 's special treatment
249 of single-value promises).
254 .. js:function:: when(deferreds…)
256 :param deferreds: deferred objects to multiplex
257 :returns: a multiplexed deferred
258 :rtype: :js:class:`Deferred`
260 .. js:class:: Deferred
262 .. js:function:: Deferred.then(doneCallback[, failCallback])
264 Attaches new callbacks to the resolution or rejection of the
265 deferred object. Callbacks are executed in the order they are
266 attached to the deferred.
268 To provide only a failure callback, pass ``null`` as the
269 ``doneCallback``, to provide only a success callback the
270 second argument can just be ignored (and not passed at all).
272 :param doneCallback: function called when the deferred is resolved
273 :type doneCallback: Function
274 :param failCallback: function called when the deferred is rejected
275 :type failCallback: Function
276 :returns: the deferred object on which it was called
277 :rtype: :js:class:`Deferred`
279 .. js:function:: Deferred.done(doneCallback)
281 Attaches a new success callback to the deferred, shortcut for
282 ``deferred.then(doneCallback)``.
284 This is a jQuery extension to `CommonJS Promises/A`_ providing
285 little value over calling :js:func:`~Deferred.then` directly,
286 it should be avoided.
288 :param doneCallback: function called when the deferred is resolved
289 :type doneCallback: Function
290 :returns: the deferred object on which it was called
291 :rtype: :js:class:`Deferred`
293 .. js:function:: Deferred.fail(failCallback)
295 Attaches a new failure callback to the deferred, shortcut for
296 ``deferred.then(null, failCallback)``.
298 A second jQuery extension to `Promises/A <CommonJS
299 Promises/A>`_. Although it provides more value than
300 :js:func:`~Deferred.done`, it still is not much and should be
303 :param failCallback: function called when the deferred is rejected
304 :type failCallback: Function
305 :returns: the deferred object on which it was called
306 :rtype: :js:class:`Deferred`
308 .. js:function:: Deferred.promise()
310 Returns a read-only view of the deferred object, with all
311 mutators (resolve and reject) methods removed.
313 .. js:function:: Deferred.resolve(value…)
315 Called to resolve a deferred, any value provided will be
316 passed onto the success handlers of the deferred object.
318 Resolving a deferred which has already been resolved or
319 rejected has no effect.
321 .. js:function:: Deferred.reject(value…)
323 Called to reject (fail) a deferred, any value provided will be
324 passed onto the failure handler of the deferred object.
326 Rejecting a deferred which has already been resolved or
327 rejected has no effect.
329 .. js:function:: Deferred.pipe(doneFilter[, failFilter])
331 Filters the result of a deferred, able to transform a success
332 into failure and a failure into success, or to delay
335 .. [#] or simply calling :js:class:`Deferred` as a function, the
338 .. [#] or not-promises, the `CommonJS Promises/B`_ role of
339 :js:func:`when` is to be able to treat values and promises
340 uniformly: :js:func:`when` will pass promises through directly,
341 but non-promise values and objects will be transformed into a
342 resolved promise (resolving themselves with the value itself).
344 jQuery's :js:func:`when` keeps this behavior making deferreds
345 easy to build from "static" values, or allowing defensive code
346 where expected promises are wrapped in :js:func:`when` just in
349 .. _promises: http://en.wikipedia.org/wiki/Promise_(programming)
350 .. _jQuery's deferred: http://api.jquery.com/category/deferred-object/
351 .. _CommonJS Promises/A: http://wiki.commonjs.org/wiki/Promises/A
352 .. _CommonJS Promises/B: http://wiki.commonjs.org/wiki/Promises/B
353 .. _mocks: http://en.wikipedia.org/wiki/Mock_object