asyncio: document the debug mode

diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst
index 9d6f054a7ce393c85ab5f4815deddb5669b21db4..2b3ad9417bc928e502ca87cbfb50681f992b795b 100644 (file)
--- a/Doc/library/asyncio-dev.rst
+++ b/Doc/library/asyncio-dev.rst
@@ -9,6 +9,29 @@ Asynchronous programming is different than classical "sequential" programming.
 This page lists common traps and explains how to avoid them.
 
 
+.. _asyncio-debug-mode:
+
+Debug mode of asyncio
+---------------------
+
+To enable the debug mode globally, set the environment variable
+:envvar:`PYTHONASYNCIODEBUG` to ``1``. Examples of effects of the debug mode:
+
+* Log :ref:`coroutines defined but never "yielded from"
+  <asyncio-coroutine-not-scheduled>`
+* :meth:`~BaseEventLoop.call_soon` and :meth:`~BaseEventLoop.call_at` methods
+  raise an exception if they are called from the wrong thread.
+* Log the execution time of the selector
+* Log callbacks taking more than 100 ms to be executed. The
+  :attr:`BaseEventLoop.slow_callback_duration` attribute is the minimum
+  duration in seconds of "slow" callbacks.
+
+.. seealso::
+
+   The :meth:`BaseEventLoop.set_debug` method and the :ref:`asyncio logger
+   <asyncio-logger>`.
+
+
 .. _asyncio-multithreading:
 
 Concurrency and multithreading
@@ -83,10 +106,10 @@ Detect coroutine objects never scheduled
 When a coroutine function is called but not passed to :func:`async` or to the
 :class:`Task` constructor, it is not scheduled and it is probably a bug.
 
-To detect such bug, set the environment variable :envvar:`PYTHONASYNCIODEBUG`
-to ``1``. When the coroutine object is destroyed by the garbage collector, a
-log will be emitted with the traceback where the coroutine function was called.
-See the :ref:`asyncio logger <asyncio-logger>`.
+To detect such bug, :ref:`enable the debug mode of asyncio
+<asyncio-debug-mode>`. When the coroutine object is destroyed by the garbage
+collector, a log will be emitted with the traceback where the coroutine
+function was called.  See the :ref:`asyncio logger <asyncio-logger>`.
 
 The debug flag changes the behaviour of the :func:`coroutine` decorator. The
 debug flag value is only used when then coroutine function is defined, not when

diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index db89a2a998f731849e1998013fa3b9ffc5e68d68..e62f5efa6389b321b6973db78d7d73806c806b63 100644 (file)
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -601,7 +601,7 @@ Debug mode
 
 .. seealso::
 
-   The :ref:`Develop with asyncio <asyncio-dev>` section.
+   The :ref:`debug mode of asyncio <asyncio-debug-mode>`.
 
 
 Server

diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index 0c3c2037e8ebd88987a1728c9130d7fec7be9154..55e0e678e9263b7dcb258e4635a10db00b976755 100644 (file)
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -616,8 +616,8 @@ conflict.
 
 .. envvar:: PYTHONASYNCIODEBUG
 
-   If this environment variable is set to a non-empty string, enable the debug
-   mode of the :mod:`asyncio` module.
+   If this environment variable is set to a non-empty string, enable the
+   :ref:`debug mode <asyncio-debug-mode>` of the :mod:`asyncio` module.
 
    .. versionadded:: 3.4