Refs #30451 -- Doc'd asynchronous support and async-safety.

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.