From 1c3b53c5db3c9c0f7a1f1650b020e6302705395b Mon Sep 17 00:00:00 2001
From: pgjones <philip.graham.jones@googlemail.com>
Date: Sat, 17 Apr 2021 11:27:38 +0100
Subject: [PATCH 1/2] Update the docs on serving with ASGI

Whilst it has been possible to serve via an ASGI server for a while
(using WSGI to ASGI middleware/adapters) it hasn't added much. Now
though it makes sense to recommend the asgiref adapter as it
integrates with the same event loop used for async route handlers
etc...
---
 docs/deploying/asgi.rst  | 27 +++++++++++++++++++++++++++
 docs/deploying/index.rst |  1 +
 2 files changed, 28 insertions(+)
 create mode 100644 docs/deploying/asgi.rst

diff --git a/docs/deploying/asgi.rst b/docs/deploying/asgi.rst
new file mode 100644
index 00000000..6e70fee7
--- /dev/null
+++ b/docs/deploying/asgi.rst
@@ -0,0 +1,27 @@
+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
diff --git a/docs/deploying/index.rst b/docs/deploying/index.rst
index 54380599..4511bf45 100644
--- a/docs/deploying/index.rst
+++ b/docs/deploying/index.rst
@@ -31,3 +31,4 @@ Self-hosted options
    mod_wsgi
    fastcgi
    cgi
+   asgi

From f74cce164e2065a866bf6d89e53fa5a4b4840cf2 Mon Sep 17 00:00:00 2001
From: pgjones <philip.graham.jones@googlemail.com>
Date: Sat, 17 Apr 2021 11:49:24 +0100
Subject: [PATCH 2/2] Update documentation on asyncio background tasks

This has been an early question from users, so best to explain.
---
 docs/async-await.rst    | 17 +++++++++++++++++
 docs/deploying/asgi.rst |  2 ++
 2 files changed, 19 insertions(+)

diff --git a/docs/async-await.rst b/docs/async-await.rst
index c8981f88..3fc24a06 100644
--- a/docs/async-await.rst
+++ b/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
 -------------------------
 
diff --git a/docs/deploying/asgi.rst b/docs/deploying/asgi.rst
index 6e70fee7..c7e04027 100644
--- a/docs/deploying/asgi.rst
+++ b/docs/deploying/asgi.rst
@@ -1,3 +1,5 @@
+.. _asgi:
+
 ASGI
 ====