From: Ben Darnell <ben@bendarnell.com>
Date: Fri, 17 Jun 2022 17:58:10 +0000 (-0400)
Subject: ioloop: Update docs for IOLoop constructor
X-Git-Tag: v6.2.0b2~2^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F3160%2Fhead;p=thirdparty%2Ftornado.git

ioloop: Update docs for IOLoop constructor

The constructor is not completely deprecated; the make_current=False
mode is still usable.

Fixes #3156
---

diff --git a/tornado/ioloop.py b/tornado/ioloop.py
index b907106ef..2c05755db 100644
--- a/tornado/ioloop.py
+++ b/tornado/ioloop.py
@@ -119,10 +119,12 @@ class IOLoop(Configurable):
     .. testoutput::
        :hide:
 
-    Do not attempt to construct an `IOLoop` directly; this is deprecated since
-    Tornado 6.2. Instead, initialize the `asyncio` event loop and use
-    `IOLoop.current()` to access an `IOLoop` wrapper around the current event
-    loop.
+    Most applications should not attempt to construct an `IOLoop` directly,
+    and instead initialize the `asyncio` event loop and use `IOLoop.current()`.
+    In some cases, such as in test frameworks when initializing an `IOLoop`
+    to be run in a secondary thread, it may be appropriate to construct
+    an `IOLoop` with ``IOLoop(make_current=False)``. Constructing an `IOLoop`
+    without the ``make_current=False`` argument is deprecated since Tornado 6.2.
 
     In general, an `IOLoop` cannot survive a fork or be shared across processes
     in any way. When multiple processes are being used, each process should