Merge pull request #3967 from pgjones/docs

docs/async-await.rst

@@ -39,6 +39,23 @@ most use cases, but Flask's async support enables writing and using
 code that wasn't possible natively before.
 
 
+Background tasks
+----------------
+
+Async functions will run in an event loop until they complete, at
+which stage the event loop will stop. This means any additional
+spawned tasks that haven't completed when the async function completes
+will be cancelled. Therefore you cannot spawn background tasks, for
+example via ``asyncio.create_task``.
+
+If you wish to use background tasks it is best to use a task queue to
+trigger background work, rather than spawn tasks in a view
+function. With that in mind you can spawn asyncio tasks by serving
+Flask with a ASGI server and utilising the asgiref WsgiToAsgi adapter
+as described in :ref:`asgi`. This works as the adapter creates an
+event loop that runs continually.
+
+
 When to use Quart instead
 -------------------------
 

docs/deploying/asgi.rst

@@ -0,0 +1,29 @@
+.. _asgi:
+
+ASGI
+====
+
+If you'd like to use an ASGI server you will need to utilise WSGI to
+ASGI middleware. The asgiref
+[WsgiToAsgi](https://github.com/django/asgiref#wsgi-to-asgi-adapter)
+adapter is recommended as it integrates with the event loop used for
+Flask's :ref:`async_await` support. You can use the adapter by
+wrapping the Flask app,
+
+.. code-block:: python
+
+    from asgiref.wsgi import WsgiToAsgi
+    from flask import Flask
+
+    app = Flask(__name__)
+
+    ...
+
+    asgi_app = WsgiToAsgi(app)
+
+and then serving the ``asgi_app`` with the asgi server, e.g. using
+`Hypercorn <https://gitlab.com/pgjones/hypercorn>`_,
+
+.. sourcecode:: text
+
+    $ hypercorn module:asgi_app

docs/deploying/index.rst

@@ -31,3 +31,4 @@ Self-hosted options
    mod_wsgi
    fastcgi
    cgi
+   asgi