diff options
| -rw-r--r-- | docs/index.txt | 3 | ||||
| -rw-r--r-- | docs/spelling_wordlist | 2 | ||||
| -rw-r--r-- | docs/topics/async.txt | 36 | ||||
| -rw-r--r-- | docs/topics/index.txt | 1 |
4 files changed, 41 insertions, 1 deletions
diff --git a/docs/index.txt b/docs/index.txt index 64a45c876d..d8ef87f777 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -110,7 +110,8 @@ manipulating the data of your Web application. Learn more about it below: :doc:`Custom lookups <howto/custom-lookups>` | :doc:`Query Expressions <ref/models/expressions>` | :doc:`Conditional Expressions <ref/models/conditional-expressions>` | - :doc:`Database Functions <ref/models/database-functions>` + :doc:`Database Functions <ref/models/database-functions>` | + :doc:`Asynchronous Support <topics/async>` * **Other:** :doc:`Supported databases <ref/databases>` | diff --git a/docs/spelling_wordlist b/docs/spelling_wordlist index 43e8a68385..9c56339cc0 100644 --- a/docs/spelling_wordlist +++ b/docs/spelling_wordlist @@ -116,6 +116,7 @@ conf config contenttypes contrib +coroutine coroutines covariance criticals @@ -664,6 +665,7 @@ th that'll Thejaswi This'll +threadpool timeframe timeline timelines 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. diff --git a/docs/topics/index.txt b/docs/topics/index.txt index 55a5fc6af3..ffb9fa9d92 100644 --- a/docs/topics/index.txt +++ b/docs/topics/index.txt @@ -31,3 +31,4 @@ Introductions to all the key parts of Django you'll need to know: signals checks external-packages + async |