Document the order pecularity for async

Related to #158.

docs/docs/async.rst

@@ -32,9 +32,8 @@ return an ``AsyncResult`` ::
     res = async_sleep(5)
 
 Which means your client can continue working normally, while the server
-performs the request. Do note, however, that the server is "busy" sleeping,
-and will not respond to new requests until the operation completes (unless you
-started your request on a separate thread)
+performs the request. There are several pitfalls using :func:`async
+<pyc.utils.helpers.async>`, be sure to read the Notes_ section!
 
 You can test for completion using ``res.ready``, wait for completion using ``res.wait()``,
 and get the result using ``res.value``. You may set a timeout for the result using
@@ -54,6 +53,10 @@ Use ::
     myfunc_async = async(conn.root.myfunc)
     res = myfunc_async(1,2,3)
 
+Furthermore, async requests provide **no guarantee on execution order**. In
+particular, multiple subsequent async requests may be executed in reverse
+order.
+
 
 timed()
 -------

docs/tutorial/tut5.rst

@@ -14,6 +14,8 @@ Instead of getting the result of the call, you get a special object known as an
 ``AsyncResult`` (also known as a `"future" or "promise" <http://en.wikipedia.org/wiki/Futures_and_promises>`_]),
 that will **eventually** hold the result.
 
+Note that there is no guarantee on execution order for async requests!
+
 In order to turn the invocation of a remote function (or any callable object) asynchronous,
 all you have to do is wrap it with :func:`async <rpyc.utils.helpers.async>`, which creates a
 wrapper function that will return an ``AsyncResult`` instead of blocking. ``AsyncResult``
@@ -214,6 +216,3 @@ incoming requests). Here's an example of that::
         new stat: (33188, 1564681L, 2051L, 1, 1011, 1011, 6L, 1225205197, 1225205218, 1225205218)
     <__main__.exposed_FileMonitor object at 0xb7a7a52c>
     >>>
-
-
-

rpyc/utils/helpers.py

@@ -125,6 +125,11 @@ def async(proxy):
 
            a_foo = rpyc.async(foo)
            a_foo(5)
+
+    .. note::
+        Furthermore, async requests provide **no guarantee on execution
+        order**. In particular, multiple subsequent async requests may be
+        executed in reverse order.
     """
     pid = id(proxy)
     if pid in _async_proxies_cache: