From 77d278d590e1dc5a80f31da32d51a56779d52e18 Mon Sep 17 00:00:00 2001 From: Ben Darnell Date: Sun, 4 Mar 2018 13:22:24 -0500 Subject: [PATCH] docs: Add a prominent warning against threads and WSGI --- docs/index.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) 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 `_. +Threads and WSGI +---------------- + +Tornado is different from most Python web frameworks. It is not based +on `WSGI `_, 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 ------------ -- 2.47.2