Add a mention of on_connection_close to the html docs. Add a

warning about proxies keeping connections open.

diff --git a/tornado/web.py b/tornado/web.py
index 4c3a8f6ac6e094254201312a0305b8f075732302..daf8b315bc7260a3bd32a08c806214427cee30fb 100644 (file)
--- a/tornado/web.py
+++ b/tornado/web.py
@@ -160,6 +160,11 @@ class RequestHandler(object):
         you try (and fail) to produce some output.  The epoll- and kqueue-
         based implementations should detect closed connections even while
         the request is idle.
+
+        Proxies may keep a connection open for a time (perhaps
+        indefinitely) after the client has gone away, so this method
+        may not be called promptly after the end user closes their
+        connection.
         """
         pass
 

diff --git a/website/templates/documentation.txt b/website/templates/documentation.txt
index 90738bbe078b30f68af83176df8cf9272ecc8cf2..5d19d6652a6beeedda27c97595ca1ced32180c54 100644 (file)
--- a/website/templates/documentation.txt
+++ b/website/templates/documentation.txt
@@ -675,6 +675,9 @@ will be properly closed.
 For a more advanced asynchronous example, take a look at the `chat` example
 application, which implements an AJAX chat room using
 [long polling](http://en.wikipedia.org/wiki/Push_technology#Long_polling).
+Users of long polling may want to override `on_connection_close()` to clean
+up after the client closes the connection (but see that method's docstring
+for caveats).
 
 
 ### Third party authentication