diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst index 9d6f054a7ce..2b3ad9417bc 100644 --- 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" + ` +* :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-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 `. +To detect such bug, :ref:`enable the debug mode of asyncio +`. 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 `. 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 db89a2a998f..e62f5efa638 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -601,7 +601,7 @@ Debug mode .. seealso:: - The :ref:`Develop with asyncio ` section. + The :ref:`debug mode of asyncio `. Server diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index 0c3c2037e8e..55e0e678e92 100644 --- 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 ` of the :mod:`asyncio` module. .. versionadded:: 3.4