Add a warning label to WSGIContainer.

diff --git a/tornado/wsgi.py b/tornado/wsgi.py
index 615f2e1fdd8c4cd0b59e6db7e9d2c77899956fdb..f21f240c220ba04b81b3e132babc6f53eaa56ea5 100644 (file)
--- a/tornado/wsgi.py
+++ b/tornado/wsgi.py
@@ -215,6 +215,16 @@ class HTTPRequest(object):
 class WSGIContainer(object):
     r"""Makes a WSGI-compatible function runnable on Tornado's HTTP server.
 
+    .. warning::
+
+       WSGI is a *synchronous* interface, while Tornado's concurrency model
+       is based on single-threaded asynchronous execution.  This means that
+       running a WSGI app with Tornado's `WSGIContainer` is *less scalable*
+       than running the same app in a multi-threaded WSGI server like
+       ``gunicorn`` or ``uwsgi``.  Use `WSGIContainer` only when there are
+       benefits to combining Tornado and WSGI in the same process that
+       outweigh the reduced scalability.
+
     Wrap a WSGI function in a `WSGIContainer` and pass it to `.HTTPServer` to
     run it. For example::