[3.0.x] Refs #30451 -- Doc'd asynchronous support and async-safety.

Backport of 635a3f8e6e from master

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>` |

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

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.

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