[Python-checkins] cpython: asyncio doc: document the granularity of the event loop

[victor.stinner]

http://hg.python.org/cpython/rev/3fea5a721344
changeset:   88873:3fea5a721344
user:        Victor Stinner <victor.stinner at gmail.com>
date:        Sat Feb 01 02:36:43 2014 +0100
summary:
  asyncio doc: document the granularity of the event loop

Improve also the "Logging" section

files:
  Doc/library/asyncio-dev.rst       |  17 +++++++++++------
  Doc/library/asyncio-eventloop.rst |  18 +++++++++++++++++-
  Doc/library/asyncio-task.rst      |   3 +++
  3 files changed, 31 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
@@ -7,6 +7,8 @@
 This page lists common traps and explains how to avoid them.
 
 
+.. _asyncio-handle-blocking:
+
 Handle correctly blocking functions
 -----------------------------------
 
@@ -21,17 +23,20 @@
 different process, to not block the thread of the event loop. See the
 :func:`BaseEventLoop.run_in_executor` function.
 
+.. seealso::
+
+   The :ref:`Delayed calls <asyncio-delayed-calls>` section details how the
+   event loop handles time.
+
 
 .. _asyncio-logger:
 
-Logger
-------
+Logging
+-------
 
-.. data:: asyncio.logger.log
+The :mod:`asyncio` module logs information with the :mod:`logging` module in
+the logger ``'asyncio'``.
 
-   :class:`logging.Logger` instance used by :mod:`asyncio` to log messages.
-
-The logger name is ``'asyncio'``.
 
 .. _asyncio-coroutine-not-scheduled:
 
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
@@ -108,6 +108,8 @@
    Like :meth:`call_soon`, but thread safe.
 
 
+.. _asyncio-delayed-calls:
+
 Delayed calls
 -------------
 
@@ -116,6 +118,20 @@
 implementation; ideally it is a monotonic clock.  This will generally be
 a different clock than :func:`time.time`.
 
+The granularity of the event loop depends on the resolution of the
+:meth:`~BaseEventLoop.time` method and the resolution of the selector. It is
+usually between 1 ms and 16 ms. For example, a granularity of 1 ms means that
+in the best case, the difference between the expected delay and the real
+elapsed time is between -1 ms and +1 ms: a call scheduled in 1 nanosecond may
+be called in 1 ms, and a call scheduled in 100 ms may be called in 99 ms.
+
+The granularity is the best difference in theory. In practice, it depends on
+the system load and the the time taken by tasks executed by the event loop.
+For example, if a task blocks the event loop for 1 second, all tasks scheduled
+in this second will be delayed. The :ref:`Handle correctly blocking functions
+<asyncio-handle-blocking>` section explains how to avoid such issue.
+
+
 .. method:: BaseEventLoop.call_later(delay, callback, *args)
 
    Arrange for the *callback* to be called after the given *delay*
@@ -290,7 +306,7 @@
 
    On Windows, the default event loop uses
    :class:`selectors.SelectSelector` which only supports sockets. The
-   :class:`ProactorEventLoop` should be used instead.
+   :class:`ProactorEventLoop` should be used to support subprocesses.
 
 .. note::
 
diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -441,6 +441,9 @@
    time (in seconds).  If *result* is provided, it is produced to the caller
    when the coroutine completes.
 
+   The resolution of the sleep depends on the :ref:`granularity of the event
+   loop <asyncio-delayed-calls>`.
+
 .. function:: shield(arg, \*, loop=None)
 
    Wait for a future, shielding it from cancellation.

-- 
Repository URL: http://hg.python.org/cpython