diff options
Diffstat (limited to 'docs/topics/async.txt')
| -rw-r--r-- | docs/topics/async.txt | 36 |
1 files changed, 36 insertions, 0 deletions
diff --git a/docs/topics/async.txt b/docs/topics/async.txt new file mode 100644 index 0000000000..6a6f0030c9 --- /dev/null +++ b/docs/topics/async.txt @@ -0,0 +1,36 @@ +==================== +Asynchronous support +==================== + +.. versionadded:: 3.0 + +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 +------------ + +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 ``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 +``asgiref.sync.async_to_sync``, or any other preferred way of running +synchronous code in its own thread. |