From: Ben Darnell <ben@bendarnell.com>
Date: Sun, 18 Jan 2015 18:13:41 +0000 (-0500)
Subject: A new IOLoop is automatically "current" if there isn't already one.
X-Git-Tag: v4.1.0b1~21
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ab6b980c42dbaff73ed63deb200f1a23467f3529;p=thirdparty%2Ftornado.git

A new IOLoop is automatically "current" if there isn't already one.

IOLoop keyword arguments throughout the library are now deprecated
in favor of IOLoop.current(). This is because the gen module
uses IOLoop.current() with no opportunity to pass in a different
instance, making it impossible in some cases to use a non-current
IOLoop with AsyncHTTPClient.

Closes #1252.
---

diff --git a/tornado/autoreload.py b/tornado/autoreload.py
index 3982579ad..a548cf026 100644
--- a/tornado/autoreload.py
+++ b/tornado/autoreload.py
@@ -108,7 +108,11 @@ _io_loops = weakref.WeakKeyDictionary()
 
 
 def start(io_loop=None, check_time=500):
-    """Begins watching source files for changes using the given `.IOLoop`. """
+    """Begins watching source files for changes.
+
+    .. versionchanged:: 4.1
+       The ``io_loop`` argument is deprecated.
+    """
     io_loop = io_loop or ioloop.IOLoop.current()
     if io_loop in _io_loops:
         return
diff --git a/tornado/gen.py b/tornado/gen.py
index e332d7a93..d6778200d 100644
--- a/tornado/gen.py
+++ b/tornado/gen.py
@@ -372,6 +372,11 @@ def Task(func, *args, **kwargs):
 
 class YieldFuture(YieldPoint):
     def __init__(self, future, io_loop=None):
+        """Adapts a `.Future` to the `YieldPoint` interface.
+
+        .. versionchanged:: 4.1
+           The ``io_loop`` argument is deprecated.
+        """
         self.future = future
         self.io_loop = io_loop or IOLoop.current()
 
diff --git a/tornado/httpclient.py b/tornado/httpclient.py
index 6ea872de2..0ae9e4802 100644
--- a/tornado/httpclient.py
+++ b/tornado/httpclient.py
@@ -137,6 +137,9 @@ class AsyncHTTPClient(Configurable):
         # or with force_instance:
         client = AsyncHTTPClient(force_instance=True,
             defaults=dict(user_agent="MyUserAgent"))
+
+    .. versionchanged:: 4.1
+       The ``io_loop`` argument is deprecated.
     """
     @classmethod
     def configurable_base(cls):
diff --git a/tornado/ioloop.py b/tornado/ioloop.py
index bbe74a15a..680dc4016 100644
--- a/tornado/ioloop.py
+++ b/tornado/ioloop.py
@@ -167,28 +167,26 @@ class IOLoop(Configurable):
             del IOLoop._instance
 
     @staticmethod
-    def current():
+    def current(instance=True):
         """Returns the current thread's `IOLoop`.
 
-        If an `IOLoop` is currently running or has been marked as current
-        by `make_current`, returns that instance.  Otherwise returns
-        `IOLoop.instance()`, i.e. the main thread's `IOLoop`.
-
-        A common pattern for classes that depend on ``IOLoops`` is to use
-        a default argument to enable programs with multiple ``IOLoops``
-        but not require the argument for simpler applications::
-
-            class MyClass(object):
-                def __init__(self, io_loop=None):
-                    self.io_loop = io_loop or IOLoop.current()
+        If an `IOLoop` is currently running or has been marked as
+        current by `make_current`, returns that instance.  If there is
+        no current `IOLoop`, returns `IOLoop.instance()` (i.e. the
+        main thread's `IOLoop`, creating one if necessary) if ``instance``
+        is true.
 
         In general you should use `IOLoop.current` as the default when
         constructing an asynchronous object, and use `IOLoop.instance`
         when you mean to communicate to the main thread from a different
         one.
+
+        .. versionchanged:: 4.1
+           Added ``instance`` argument to control the
+
         """
         current = getattr(IOLoop._current, "instance", None)
-        if current is None:
+        if current is None and instance:
             return IOLoop.instance()
         return current
 
@@ -200,6 +198,10 @@ class IOLoop(Configurable):
         `make_current` explicitly before starting the `IOLoop`,
         so that code run at startup time can find the right
         instance.
+
+        .. versionchanged:: 4.1
+           An `IOLoop` created while there is no current `IOLoop`
+           will automatically become current.
         """
         IOLoop._current.instance = self
 
@@ -224,7 +226,8 @@ class IOLoop(Configurable):
         return SelectIOLoop
 
     def initialize(self):
-        pass
+        if IOLoop.current(instance=False) is None:
+            self.make_current()
 
     def close(self, all_fds=False):
         """Closes the `IOLoop`, freeing any resources used.
@@ -946,6 +949,9 @@ class PeriodicCallback(object):
     The callback is called every ``callback_time`` milliseconds.
 
     `start` must be called after the `PeriodicCallback` is created.
+
+    .. versionchanged:: 4.1
+       The ``io_loop`` argument is deprecated.
     """
     def __init__(self, callback, callback_time, io_loop=None):
         self.callback = callback
diff --git a/tornado/iostream.py b/tornado/iostream.py
index 67a9c610c..d14ec0fdb 100644
--- a/tornado/iostream.py
+++ b/tornado/iostream.py
@@ -122,6 +122,7 @@ class BaseIOStream(object):
         """`BaseIOStream` constructor.
 
         :arg io_loop: The `.IOLoop` to use; defaults to `.IOLoop.current`.
+                      Deprecated since Tornado 4.1.
         :arg max_buffer_size: Maximum amount of incoming data to buffer;
             defaults to 100MB.
         :arg read_chunk_size: Amount of data to read at one time from the
diff --git a/tornado/netutil.py b/tornado/netutil.py
index e85f62b78..17e958040 100644
--- a/tornado/netutil.py
+++ b/tornado/netutil.py
@@ -187,6 +187,9 @@ def add_accept_handler(sock, callback, io_loop=None):
     address of the other end of the connection).  Note that this signature
     is different from the ``callback(fd, events)`` signature used for
     `.IOLoop` handlers.
+
+    .. versionchanged:: 4.1
+       The ``io_loop`` argument is deprecated.
     """
     if io_loop is None:
         io_loop = IOLoop.current()
@@ -301,6 +304,9 @@ class ExecutorResolver(Resolver):
     The executor will be shut down when the resolver is closed unless
     ``close_resolver=False``; use this if you want to reuse the same
     executor elsewhere.
+
+    .. versionchanged:: 4.1
+       The ``io_loop`` argument is deprecated.
     """
     def initialize(self, io_loop=None, executor=None, close_executor=True):
         self.io_loop = io_loop or IOLoop.current()
diff --git a/tornado/platform/caresresolver.py b/tornado/platform/caresresolver.py
index c4648c222..5559614f5 100644
--- a/tornado/platform/caresresolver.py
+++ b/tornado/platform/caresresolver.py
@@ -18,6 +18,9 @@ class CaresResolver(Resolver):
     so it is only recommended for use in ``AF_INET`` (i.e. IPv4).  This is
     the default for ``tornado.simple_httpclient``, but other libraries
     may default to ``AF_UNSPEC``.
+
+    .. versionchanged:: 4.1
+       The ``io_loop`` argument is deprecated.
     """
     def initialize(self, io_loop=None):
         self.io_loop = io_loop or IOLoop.current()
diff --git a/tornado/platform/twisted.py b/tornado/platform/twisted.py
index 27d991cdb..ccb44de8b 100644
--- a/tornado/platform/twisted.py
+++ b/tornado/platform/twisted.py
@@ -147,6 +147,9 @@ class TornadoReactor(PosixReactorBase):
     We override `mainLoop` instead of `doIteration` and must implement
     timed call functionality on top of `IOLoop.add_timeout` rather than
     using the implementation in `PosixReactorBase`.
+
+    .. versionchanged:: 4.1
+       The ``io_loop`` argument is deprecated.
     """
     def __init__(self, io_loop=None):
         if not io_loop:
@@ -356,7 +359,11 @@ class _TestReactor(TornadoReactor):
 
 
 def install(io_loop=None):
-    """Install this package as the default Twisted reactor."""
+    """Install this package as the default Twisted reactor.
+
+    .. versionchanged:: 4.1
+       The ``io_loop`` argument is deprecated.
+    """
     if not io_loop:
         io_loop = tornado.ioloop.IOLoop.current()
     reactor = TornadoReactor(io_loop)
@@ -512,6 +519,9 @@ class TwistedResolver(Resolver):
     ``socket.AF_UNSPEC``.
 
     Requires Twisted 12.1 or newer.
+
+    .. versionchanged:: 4.1
+       The ``io_loop`` argument is deprecated.
     """
     def initialize(self, io_loop=None):
         self.io_loop = io_loop or IOLoop.current()
diff --git a/tornado/process.py b/tornado/process.py
index cea3dbd01..3790ca0a5 100644
--- a/tornado/process.py
+++ b/tornado/process.py
@@ -191,6 +191,9 @@ class Subprocess(object):
       ``tornado.process.Subprocess.STREAM``, which will make the corresponding
       attribute of the resulting Subprocess a `.PipeIOStream`.
     * A new keyword argument ``io_loop`` may be used to pass in an IOLoop.
+
+    .. versionchanged:: 4.1
+       The ``io_loop`` argument is deprecated.
     """
     STREAM = object()
 
@@ -263,6 +266,9 @@ class Subprocess(object):
         Note that the `.IOLoop` used for signal handling need not be the
         same one used by individual Subprocess objects (as long as the
         ``IOLoops`` are each running in separate threads).
+
+        .. versionchanged:: 4.1
+           The ``io_loop`` argument is deprecated.
         """
         if cls._initialized:
             return
diff --git a/tornado/tcpclient.py b/tornado/tcpclient.py
index 163e5c16a..f594d91b8 100644
--- a/tornado/tcpclient.py
+++ b/tornado/tcpclient.py
@@ -136,6 +136,9 @@ class _Connector(object):
 
 class TCPClient(object):
     """A non-blocking TCP connection factory.
+
+    .. versionchanged:: 4.1
+       The ``io_loop`` argument is deprecated.
     """
     def __init__(self, resolver=None, io_loop=None):
         self.io_loop = io_loop or IOLoop.current()
diff --git a/tornado/websocket.py b/tornado/websocket.py
index 163a8b85c..f11880887 100644
--- a/tornado/websocket.py
+++ b/tornado/websocket.py
@@ -986,7 +986,7 @@ def websocket_connect(url, io_loop=None, callback=None, connect_timeout=None,
        Also accepts ``HTTPRequest`` objects in place of urls.
 
     .. versionchanged:: 4.1
-       Added ``compression_options``.
+       Added ``compression_options``. The ``io_loop`` argument is deprecated.
     """
     if io_loop is None:
         io_loop = IOLoop.current()