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 new file mode 100644 index 00000000..c7e04027 --- /dev/null +++ b/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 `_, + +.. 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