Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[3.0.x] Refs #30451 -- Doc'd asynchronous support and async-safety.
Backport of 635a3f8 from master
- Loading branch information
1 parent
830a5bc
commit 45de0c2
Showing
4 changed files
with
41 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -31,3 +31,4 @@ Introductions to all the key parts of Django you'll need to know: | |
signals | ||
checks | ||
external-packages | ||
async |