docs: Add a prominent warning against threads and WSGI

diff --git a/docs/index.rst b/docs/index.rst
index ce4156c4fcb8579788c72f4bff5b28bf54f155b0..0892e92c22b5f99e5c5c2ce79527a2ed49c44611 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -52,6 +52,28 @@ This example does not use any of Tornado's asynchronous features; for
 that see this `simple chat room
 <https://github.com/tornadoweb/tornado/tree/stable/demos/chat>`_.
 
+Threads and WSGI
+----------------
+
+Tornado is different from most Python web frameworks. It is not based
+on `WSGI <https://wsgi.readthedocs.io/en/latest/>`_, and it is
+typically run with only one thread per process. See the :doc:`guide`
+for more on Tornado's approach to asynchronous programming.
+
+While some support of WSGI is available in the `tornado.wsgi` module,
+it is not a focus of development and most applications should be
+written to use Tornado's own interfaces (such as `tornado.web`)
+directly instead of using WSGI.
+
+In general, Tornado code is not thread-safe. The only method in
+Tornado that is safe to call from other threads is
+`.IOLoop.add_callback`. You can also use `.IOLoop.run_in_executor` to
+asynchronously run a blocking function on another thread, but note
+that the function passed to ``run_in_executor`` should avoid
+referencing any Tornado objects. ``run_in_executor`` is the
+recommended way to interact with blocking code.
+
+
 Installation
 ------------