From df6db5594ddf46aaf59566c7b1e5ffd247e75d6a Mon Sep 17 00:00:00 2001
From: Ben Darnell <ben@bendarnell.com>
Date: Sat, 18 Jan 2014 15:41:03 -0500
Subject: [PATCH] Document file descriptor change and start new release notes.

---
 docs/ioloop.rst        |  6 ++++++
 docs/releases.rst      |  1 +
 docs/releases/next.rst | 24 ++++++++++++++++++++++++
 tornado/ioloop.py      | 31 +++++++++++++++++++++++++++----
 4 files changed, 58 insertions(+), 4 deletions(-)
 create mode 100644 docs/releases/next.rst

diff --git a/docs/ioloop.rst b/docs/ioloop.rst
index 1ddbac44..6978c39c 100644
--- a/docs/ioloop.rst
+++ b/docs/ioloop.rst
@@ -47,3 +47,9 @@
    .. automethod:: IOLoop.set_blocking_signal_threshold
    .. automethod:: IOLoop.set_blocking_log_threshold
    .. automethod:: IOLoop.log_stack
+
+   Methods for subclasses
+   ^^^^^^^^^^^^^^^^^^^^^^
+
+   .. automethod:: IOLoop.close_fd
+   .. automethod:: IOLoop.split_fd
diff --git a/docs/releases.rst b/docs/releases.rst
index a4d12a70..00e7b740 100644
--- a/docs/releases.rst
+++ b/docs/releases.rst
@@ -4,6 +4,7 @@ Release notes
 .. toctree::
    :maxdepth: 2
 
+   releases/next
    releases/v3.2.0
    releases/v3.1.1
    releases/v3.1.0
diff --git a/docs/releases/next.rst b/docs/releases/next.rst
new file mode 100644
index 00000000..0a6d5521
--- /dev/null
+++ b/docs/releases/next.rst
@@ -0,0 +1,24 @@
+What's new in the next version of Tornado
+=========================================
+
+In progress
+-----------
+
+Backwards-compatibility notes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Authors of alternative `.IOLoop` implementations should see the changes
+  to `.IOLoop.add_handler` in this release.
+
+`tornado.ioloop`
+~~~~~~~~~~~~~~~~
+
+* `.IOLoop.add_handler` and related methods now accept file-like objects
+  in addition to raw file descriptors.  Passing the objects is recommended
+  (when possible) to avoid a garbage-collection-related problem in unit tests.
+
+`tornado.websocket`
+~~~~~~~~~~~~~~~~~~~
+
+* The C speedup module now builds correctly with MSVC, and can support
+  messages larger than 2GB on 64-bit systems.
diff --git a/tornado/ioloop.py b/tornado/ioloop.py
index 18486614..da3d789e 100644
--- a/tornado/ioloop.py
+++ b/tornado/ioloop.py
@@ -244,21 +244,40 @@ class IOLoop(Configurable):
         raise NotImplementedError()
 
     def add_handler(self, fd, handler, events):
-        """Registers the given handler to receive the given events for fd.
+        """Registers the given handler to receive the given events for ``fd``.
+
+        The ``fd`` argument may either be an integer file descriptor or
+        a file-like object with a ``fileno()`` method (and optionally a
+        ``close()`` method, which may be called when the `IOLoop` is shut
+        down).
 
         The ``events`` argument is a bitwise or of the constants
         ``IOLoop.READ``, ``IOLoop.WRITE``, and ``IOLoop.ERROR``.
 
         When an event occurs, ``handler(fd, events)`` will be run.
+
+        .. versionchanged:: 3.3
+           Added the ability to pass file-like objects in addition to
+           raw file descriptors.
         """
         raise NotImplementedError()
 
     def update_handler(self, fd, events):
-        """Changes the events we listen for fd."""
+        """Changes the events we listen for ``fd``.
+
+        .. versionchanged:: 3.3
+           Added the ability to pass file-like objects in addition to
+           raw file descriptors.
+        """
         raise NotImplementedError()
 
     def remove_handler(self, fd):
-        """Stop listening for events on fd."""
+        """Stop listening for events on ``fd``.
+
+        .. versionchanged:: 3.3
+           Added the ability to pass file-like objects in addition to
+           raw file descriptors.
+        """
         raise NotImplementedError()
 
     def set_blocking_signal_threshold(self, seconds, action):
@@ -503,6 +522,8 @@ class IOLoop(Configurable):
 
         This method is provided for use by `IOLoop` subclasses and should
         not generally be used by application code.
+
+        .. versionadded:: 3.3
         """
         try:
             return fd.fileno(), fd
@@ -513,11 +534,13 @@ class IOLoop(Configurable):
         """Utility method to close an ``fd``.
 
         If ``fd`` is a file-like object, we close it directly; otherwise
-        we use `os.close()`.
+        we use `os.close`.
 
         This method is provided for use by `IOLoop` subclasses (in
         implementations of ``IOLoop.close(all_fds=True)`` and should
         not generally be used by application code.
+
+        .. versionadded:: 3.3
         """
         try:
             try: