From: Ben Darnell <ben@bendarnell.com>
Date: Sun, 4 Mar 2018 18:22:24 +0000 (-0500)
Subject: docs: Add a prominent warning against threads and WSGI
X-Git-Tag: v5.0.0~1^2~1
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=77d278d590e1dc5a80f31da32d51a56779d52e18;p=thirdparty%2Ftornado.git

docs: Add a prominent warning against threads and WSGI
---

diff --git a/docs/index.rst b/docs/index.rst
index ce4156c4f..0892e92c2 100644
--- 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
 ------------