[Python-checkins] cpython (merge 3.4 -> default): (Merge 3.4) asyncio: document the debug mode
victor.stinner
python-checkins at python.org
Mon Jun 23 00:46:27 CEST 2014
http://hg.python.org/cpython/rev/302f257823e8
changeset: 91332:302f257823e8
parent: 91330:188970f81ef8
parent: 91331:46440d260af1
user: Victor Stinner <victor.stinner at gmail.com>
date: Mon Jun 23 00:46:16 2014 +0200
summary:
(Merge 3.4) asyncio: document the debug mode
files:
Doc/library/asyncio-dev.rst | 31 ++++++++++++++++--
Doc/library/asyncio-eventloop.rst | 2 +-
Doc/using/cmdline.rst | 4 +-
3 files changed, 30 insertions(+), 7 deletions(-)
diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst
--- a/Doc/library/asyncio-dev.rst
+++ b/Doc/library/asyncio-dev.rst
@@ -9,6 +9,29 @@
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 @@
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
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -601,7 +601,7 @@
.. 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
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -616,8 +616,8 @@
.. 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
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list