Async requests docs

diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst
index ae7827c..e8c812a 100644 (file)
--- a/docs/user/advanced.rst
+++ b/docs/user/advanced.rst
@@ -43,6 +43,40 @@ Sessions can also be used to provide default data to the request methods::
     (e.g.. a global proxy, user agent header).
 
 
+Asynchronous Requests
+----------------------
+
+Requests has first-class support for non-blocking i/o requests, powered
+by gevent. This allows you to send a bunch of HTTP requests at the same
+
+First, let's import the async module. Heads up — if you don't have
+**gevent** installed, this will fail.::
+
+    from requests import async
+
+The ``async`` module has the exact same api as ``requests``, except it
+doesn't send the request immediately. Instead, it returns the ``Request``
+object.
+
+We can build a list of ``Request`` objects easily::
+
+    urls = [
+        'http://python-requests.org',
+        'http://httpbin.org',
+        'http://python-guide.org',
+        'http://kennethreitz.com'
+    ]
+
+    rs = [async.get(u) for u in urls]
+
+Now we have a list of ``Request`` objects, ready to be sent. We could
+send them one at a time with ``Request.send()``, but that would take a while.
+Instead, we'll send them all at the same time with ``async.map()``::
+
+    >>> async.map(rs)
+    [<Response [200]>, <Response [200]>, <Response [200]>, <Response [200]>]
+
+
 Event Hooks
 -----------