From: Ben Darnell <ben@bendarnell.com>
Date: Wed, 12 Jan 2011 20:14:57 +0000 (-0800)
Subject: Add some comments about thread safety.
X-Git-Tag: v1.2.0~47
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c270662df06bdd108813e4bbda7a1b5d44e77d6e;p=thirdparty%2Ftornado.git

Add some comments about thread safety.
---

diff --git a/tornado/ioloop.py b/tornado/ioloop.py
index 203820609..a7445d7cd 100644
--- 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 ceb43e24b..89ebe886a 100644
--- 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