mirror of
https://github.com/django/django.git
synced 2024-11-29 22:56:46 +01:00
160 lines
6.4 KiB
Plaintext
160 lines
6.4 KiB
Plaintext
====================
|
|
Asynchronous support
|
|
====================
|
|
|
|
.. versionadded:: 3.0
|
|
|
|
.. currentmodule:: asgiref.sync
|
|
|
|
Django has developing support for asynchronous ("async") Python, but does not
|
|
yet support asynchronous views or middleware; they will be coming in a future
|
|
release.
|
|
|
|
There is limited support for other parts of the async ecosystem; namely, Django
|
|
can natively talk :doc:`ASGI </howto/deployment/asgi/index>`, and some async
|
|
safety support.
|
|
|
|
.. _async-safety:
|
|
|
|
Async-safety
|
|
============
|
|
|
|
Certain key parts of Django are not able to operate safely in an asynchronous
|
|
environment, as they have global state that is not coroutine-aware. These parts
|
|
of Django are classified as "async-unsafe", and are protected from execution in
|
|
an asynchronous environment. The ORM is the main example, but there are other
|
|
parts that are also protected in this way.
|
|
|
|
If you try to run any of these parts from a thread where there is a *running
|
|
event loop*, you will get a
|
|
:exc:`~django.core.exceptions.SynchronousOnlyOperation` error. Note that you
|
|
don't have to be inside an async function directly to have this error occur. If
|
|
you have called a synchronous function directly from an asynchronous function
|
|
without going through something like :func:`sync_to_async` or a threadpool,
|
|
then it can also occur, as your code is still running in an asynchronous
|
|
context.
|
|
|
|
If you encounter this error, you should fix your code to not call the offending
|
|
code from an async context; instead, write your code that talks to async-unsafe
|
|
in its own, synchronous function, and call that using
|
|
:func:`asgiref.sync.async_to_sync`, or any other preferred way of running
|
|
synchronous code in its own thread.
|
|
|
|
If you are *absolutely* in dire need to run this code from an asynchronous
|
|
context - for example, it is being forced on you by an external environment,
|
|
and you are sure there is no chance of it being run concurrently (e.g. you are
|
|
in a Jupyter_ notebook), then you can disable the warning with the
|
|
``DJANGO_ALLOW_ASYNC_UNSAFE`` environment variable.
|
|
|
|
.. warning::
|
|
|
|
If you enable this option and there is concurrent access to the
|
|
async-unsafe parts of Django, you may suffer data loss or corruption. Be
|
|
very careful and do not use this in production environments.
|
|
|
|
If you need to do this from within Python, do that with ``os.environ``::
|
|
|
|
os.environ["DJANGO_ALLOW_ASYNC_UNSAFE"] = "true"
|
|
|
|
.. _Jupyter: https://jupyter.org/
|
|
|
|
Async adapter functions
|
|
=======================
|
|
|
|
It is necessary to adapt the calling style when calling synchronous code from
|
|
an asynchronous context, or vice-versa. For this there are two adapter
|
|
functions, made available from the ``asgiref.sync`` package:
|
|
:func:`async_to_sync` and :func:`sync_to_async`. They are used to transition
|
|
between sync and async calling styles while preserving compatibility.
|
|
|
|
These adapter functions are widely used in Django. The `asgiref`_ package
|
|
itself is part of the Django project, and it is automatically installed as a
|
|
dependency when you install Django with ``pip``.
|
|
|
|
.. _asgiref: https://pypi.org/project/asgiref/
|
|
|
|
``async_to_sync()``
|
|
-------------------
|
|
|
|
.. function:: async_to_sync(async_function, force_new_loop=False)
|
|
|
|
Wraps an asynchronous function and returns a synchronous function in its place.
|
|
Can be used as either a direct wrapper or a decorator::
|
|
|
|
from asgiref.sync import async_to_sync
|
|
|
|
sync_function = async_to_sync(async_function)
|
|
|
|
@async_to_sync
|
|
async def async_function(...):
|
|
...
|
|
|
|
The asynchronous function is run in the event loop for the current thread, if
|
|
one is present. If there is no current event loop, a new event loop is spun up
|
|
specifically for the async function and shut down again once it completes. In
|
|
either situation, the async function will execute on a different thread to the
|
|
calling code.
|
|
|
|
Threadlocals and contextvars values are preserved across the boundary in both
|
|
directions.
|
|
|
|
:func:`async_to_sync` is essentially a more powerful version of the
|
|
:py:func:`asyncio.run` function available in Python's standard library. As well
|
|
as ensuring threadlocals work, it also enables the ``thread_sensitive`` mode of
|
|
:func:`sync_to_async` when that wrapper is used below it.
|
|
|
|
``sync_to_async()``
|
|
-------------------
|
|
|
|
.. function:: sync_to_async(sync_function, thread_sensitive=False)
|
|
|
|
Wraps a synchronous function and returns an asynchronous (awaitable) function
|
|
in its place. Can be used as either a direct wrapper or a decorator::
|
|
|
|
from asgiref.sync import sync_to_async
|
|
|
|
async_function = sync_to_async(sync_function)
|
|
async_function = sync_to_async(sensitive_sync_function, thread_sensitive=True)
|
|
|
|
@sync_to_async
|
|
def sync_function(...):
|
|
...
|
|
|
|
@sync_to_async(thread_sensitive=True)
|
|
def sensitive_sync_function(...):
|
|
...
|
|
|
|
Threadlocals and contextvars values are preserved across the boundary in both
|
|
directions.
|
|
|
|
Synchronous functions tend to be written assuming they all run in the main
|
|
thread, so :func:`sync_to_async` has two threading modes:
|
|
|
|
* ``thread_sensitive=False`` (the default): the synchronous function will run
|
|
in a brand new thread which is then closed once it completes.
|
|
|
|
* ``thread_sensitive=True``: the synchronous function will run in the same
|
|
thread as all other ``thread_sensitive`` functions, and this will be the main
|
|
thread, if the main thread is synchronous and you are using the
|
|
:func:`async_to_sync` wrapper.
|
|
|
|
Thread-sensitive mode is quite special, and does a lot of work to run all
|
|
functions in the same thread. Note, though, that it *relies on usage of*
|
|
:func:`async_to_sync` *above it in the stack* to correctly run things on the
|
|
main thread. If you use ``asyncio.run()`` (or other options instead), it will
|
|
fall back to just running thread-sensitive functions in a single, shared thread
|
|
(but not the main thread).
|
|
|
|
The reason this is needed in Django is that many libraries, specifically
|
|
database adapters, require that they are accessed in the same thread that they
|
|
were created in, and a lot of existing Django code assumes it all runs in the
|
|
same thread (e.g. middleware adding things to a request for later use by a
|
|
view).
|
|
|
|
Rather than introduce potential compatibility issues with this code, we instead
|
|
opted to add this mode so that all existing Django synchronous code runs in the
|
|
same thread and thus is fully compatible with asynchronous mode. Note, that
|
|
synchronous code will always be in a *different* thread to any async code that
|
|
is calling it, so you should avoid passing raw database handles or other
|
|
thread-sensitive references around in any new code you write.
|