Add some comments about thread safety.

tornado/ioloop.py

@@ -322,7 +322,14 @@ def remove_timeout(self, timeout):
         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()
 

tornado/web.py

@@ -39,6 +39,14 @@ def get(self):
 
 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