Add some comments about thread safety.

diff --git a/tornado/ioloop.py b/tornado/ioloop.py
index 20382060928669c9a65b57ceff6c05e5e3991ef9..a7445d7cda455ea4d2fb05f14904297264de635b 100644 (file)
--- a/tornado/ioloop.py
+++ b/tornado/ioloop.py
@@ -322,7 +322,14 @@ class IOLoop(object):
         self._timeouts.remove(timeout)
 
     def add_callback(self, callback):
-        """Calls the given callback on the next I/O loop iteration."""
+        """Calls the given callback on the next I/O loop iteration.
+
+        It is safe to call this method from any thread at any time.
+        Note that this is the *only* method in IOLoop that makes this
+        guarantee; all other interaction with the IOLoop must be done
+        from that IOLoop's thread.  add_callback() may be used to transfer
+        control from other threads to the IOLoop's thread.
+        """
         self._callbacks.append(stack_context.wrap(callback))
         self._wake()
 

diff --git a/tornado/web.py b/tornado/web.py
index ceb43e24b6b5f7bd95323407a9a5f9c5f66a045f..89ebe886ab3578c622fdcd3181933811c6868f8f 100644 (file)
--- a/tornado/web.py
+++ b/tornado/web.py
@@ -39,6 +39,14 @@ Here is the canonical "Hello, world" example app:
 
 See the Tornado walkthrough on http://tornadoweb.org for more details
 and a good getting started guide.
+
+Thread-safety notes:
+
+In general, methods on RequestHandler and elsewhere in tornado are not
+thread-safe.  In particular, methods such as write(), finish(), and
+flush() must only be called from the main thread.  If you use multiple
+threads it is important to use IOLoop.add_callback to transfer control
+back to the main thread before finishing the request.
 """
 
 from __future__ import with_statement