async.rst

Ajax下日志框架

    If additional arguments are given, then ``func`` will be replaced
    with :mochiref:`MochiKit.Base.partial.apply(null, arguments)`. This
    differs from `Twisted`_, because the result of the errback will
    be the *last* argument passed to ``func``.

    If ``func`` returns a :mochiref:`Deferred`, then it will be chained
    (its value or error will be passed to the next callback). Note that
    once the returned ``Deferred`` is chained, it can no longer accept new
    callbacks.

:mochidef:`Deferred.prototype.callback([result])`:

    Begin the callback sequence with a non-``Error`` result. Result
    may be any value except for a :mochiref:`Deferred`.
    
    Either ``.callback`` or ``.errback`` should
    be called exactly once on a :mochiref:`Deferred`.


:mochidef:`Deferred.prototype.cancel()`:

    Cancels a :mochiref:`Deferred` that has not yet received a value,
    or is waiting on another :mochiref:`Deferred` as its value.

    If a canceller is defined, the canceller is called.
    If the canceller did not return an ``Error``, or there
    was no canceller, then the errback chain is started
    with :mochiref:`CancelledError`.
        

:mochidef:`Deferred.prototype.errback([result])`:

    Begin the callback sequence with an error result.
    Result may be any value except for a :mochiref:`Deferred`,
    but if ``!(result instanceof Error)``, it will be wrapped
    with :mochiref:`GenericError`.

    Either ``.callback`` or ``.errback`` should
    be called exactly once on a :mochidef:`Deferred`.


:mochidef:`DeferredLock()`:

    A lock for asynchronous systems.

    The ``locked`` property of a :mochiref:`DeferredLock` will be ``true`` if
    it locked, ``false`` otherwise. Do not change this property.


:mochidef:`DeferredLock.prototype.acquire()`:

    Attempt to acquire the lock. Returns a :mochiref:`Deferred` that fires on
    lock acquisition with the :mochiref:`DeferredLock` as the value.
    If the lock is locked, then the :mochiref:`Deferred` goes into a waiting
    list.


:mochidef:`DeferredLock.prototype.release()`:
    
    Release the lock. If there is a waiting list, then the first
    :mochiref:`Deferred` in that waiting list will be called back.


:mochidef:`DeferredList(list, [fireOnOneCallback, fireOnOneErrback, consumeErrors, canceller])`:

    Combine a list of :mochiref:`Deferred` into one. Track the callbacks and 
    return a list of (success, result) tuples, 'success' being a boolean 
    indicating whether result is a normal result or an error.

    Once created, you have access to all :mochiref:`Deferred` methods, like
    addCallback, addErrback, addBoth. The behaviour can be changed by the
    following options:

    ``fireOnOneCallback``:
        Flag for launching the callback once the first Deferred of the list
        has returned.

    ``fireOnOneErrback``:
        Flag for calling the errback at the first error of a Deferred.

    ``consumeErrors``:
        Flag indicating that any errors raised in the Deferreds should be
        consumed by the DeferredList.

    Example::

        // We need to fetch data from 2 different urls
        var d1 = loadJSONDoc(url1);
        var d2 = loadJSONDoc(url2);
        var l1 = new DeferredList([d1, d2], false, false, true);
        l1.addCallback(function (resultList) {
            MochiKit.Base.map(function (result) {
                if (result[0]) {
                    alert("Data is here: " + result[1]);
                } else {
                    alert("Got an error: " + result[1]);
                }
            }, resultList);
        });
        

Functions
---------

:mochidef:`callLater(seconds, func[, args...])`:

    Call ``func(args...)`` after at least ``seconds`` seconds have elapsed.
    This is a convenience method for::

        func = partial.apply(extend(null, arguments, 1));
        return wait(seconds).addCallback(function (res) { return func() });

    Returns a cancellable :mochiref:`Deferred`.


:mochidef:`doSimpleXMLHttpRequest(url[, queryArguments...])`:

    Perform a simple ``XMLHttpRequest`` and wrap it with a
    :mochiref:`Deferred` that may be cancelled. 

    Note that currently, only ``200`` (OK) and ``304``
    (NOT_MODIFIED) are considered success codes at this time, other
    status codes will result in an errback with an ``XMLHttpRequestError``.

    ``url``:
        The URL to GET

    ``queryArguments``:
        If this function is called with more than one argument, a ``"?"``
        and the result of :mochiref:`MochiKit.Base.queryString` with
        the rest of the arguments are appended to the URL.

        For example, this will do a GET request to the URL
        ``http://example.com?bar=baz``::
        
            doSimpleXMLHttpRequest("http://example.com", {bar: "baz"});

    *returns*:
        :mochiref:`Deferred` that will callback with the ``XMLHttpRequest``
        instance on success
    

:mochidef:`evalJSONRequest(req)`:

    Evaluate a JSON [4]_ ``XMLHttpRequest``

    ``req``:
        The request whose ``.responseText`` property is to be evaluated

    *returns*:
        A JavaScript object


:mochidef:`fail([result])`:

    Return a :mochiref:`Deferred` that has already had ``.errback(result)``
    called.

    See ``succeed`` documentation for rationale.

    ``result``:
        The result to give to :mochiref:`Deferred.prototype.errback(result)`.

    *returns*:
        A ``new`` :mochiref:`Deferred()`


:mochidef:`gatherResults(deferreds)`:

    A convenience function that returns a :mochiref:`DeferredList`
    from the given ``Array`` of :mochiref:`Deferred` instances
    that will callback with an ``Array`` of just results when
    they're available, or errback on the first array.


:mochidef:`getXMLHttpRequest()`:

    Return an ``XMLHttpRequest`` compliant object for the current
    platform.

    In order of preference:

    - ``new XMLHttpRequest()``
    - ``new ActiveXObject('Msxml2.XMLHTTP')``
    - ``new ActiveXObject('Microsoft.XMLHTTP')``
    - ``new ActiveXObject('Msxml2.XMLHTTP.4.0')``


:mochidef:`maybeDeferred(func[, argument...])`:

    Call a ``func`` with the given arguments and ensure the result is a
    :mochiref:`Deferred`.

    ``func``:
        The function to call.

    *returns*:
        A new :mochiref:`Deferred` based on the call to ``func``. If ``func``
        does not naturally return a :mochiref:`Deferred`, its result or error
        value will be wrapped by one.


:mochidef:`loadJSONDoc(url)`:

    Do a simple ``XMLHttpRequest`` to a URL and get the response
    as a JSON [4]_ document.

    ``url``:
        The URL to GET

    *returns*:
        :mochiref:`Deferred` that will callback with the evaluated JSON [4]_
        response upon successful ``XMLHttpRequest``


:mochidef:`sendXMLHttpRequest(req[, sendContent])`:

    Set an ``onreadystatechange`` handler on an ``XMLHttpRequest`` object
    and send it off. Will return a cancellable :mochiref:`Deferred` that will
    callback on success.
    
    Note that currently, only ``200`` (OK) and ``304``
    (NOT_MODIFIED) are considered success codes at this time, other
    status codes will result in an errback with an ``XMLHttpRequestError``.

    ``req``:
        An preconfigured ``XMLHttpRequest`` object (open has been called).

    ``sendContent``:
        Optional string or DOM content to send over the ``XMLHttpRequest``.

    *returns*:
        :mochiref:`Deferred` that will callback with the ``XMLHttpRequest``
        instance on success.


:mochidef:`succeed([result])`:

    Return a :mochiref:`Deferred` that has already had ``.callback(result)``
    called.

    This is useful when you're writing synchronous code to an asynchronous
    interface: i.e., some code is calling you expecting a :mochiref:`Deferred`
    result, but you don't actually need to do anything asynchronous. Just
    return ``succeed(theResult)``.

    See ``fail`` for a version of this function that uses a failing
    :mochiref:`Deferred` rather than a successful one.

    ``result``:
        The result to give to :mochiref:`Deferred.prototype.callback(result)`

    *returns*:
        a ``new`` :mochiref:`Deferred`

   
:mochidef:`wait(seconds[, res])`:

    Return a new cancellable :mochiref:`Deferred` that will ``.callback(res)``
    after at least ``seconds`` seconds have elapsed.


See Also
========

.. [1] AJAX, Asynchronous JavaScript and XML: http://en.wikipedia.org/wiki/AJAX
.. [2] Twisted, an event-driven networking framework written in Python: http://twistedmatrix.com/
.. [3] Twisted Deferred Reference: http://twistedmatrix.com/projects/core/documentation/howto/defer.html
.. [4] JSON, JavaScript Object Notation: http://json.org/


Authors
=======

- Bob Ippolito <[e-mail]>


Copyright
=========

Copyright 2005 Bob Ippolito <[e-mail]>. This program is dual-licensed
free software; you can redistribute it and/or modify it under the terms of the
`MIT License`_ or the `Academic Free License v2.1`_.

.. _`MIT License`: http://www.opensource.org/licenses/mit-license.php
.. _`Academic Free License v2.1`: http://www.opensource.org/licenses/afl-2.1.php