asyncio doc: document the granularity of the event loop

Improve also the "Logging" section

3 files changed, 31 insertions, 7 deletions

diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst
index 73cc38a..868e3f8 100644
--- a/Doc/library/asyncio-dev.rst
+++ b/Doc/library/asyncio-dev.rst
@@ -7,6 +7,8 @@ Asynchronous programming is different than classical "sequential" programming.
 This page lists common traps and explains how to avoid them.
 
 
+.. _asyncio-handle-blocking:
+
 Handle correctly blocking functions
 -----------------------------------
 
@@ -21,17 +23,20 @@ An executor can be used to run a task in a different thread or even in a
 different process, to not block the thread of the event loop. See the
 :func:`BaseEventLoop.run_in_executor` function.
 
+.. seealso::
 
-.. _asyncio-logger:
+   The :ref:`Delayed calls <asyncio-delayed-calls>` section details how the
+   event loop handles time.
 
-Logger
-------
 
-.. data:: asyncio.logger.log
+.. _asyncio-logger:
+
+Logging
+-------
 
-   :class:`logging.Logger` instance used by :mod:`asyncio` to log messages.
+The :mod:`asyncio` module logs information with the :mod:`logging` module in
+the logger ``'asyncio'``.
 
-The logger name is ``'asyncio'``.
 
 .. _asyncio-coroutine-not-scheduled:
 
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index f74b557..cb6f78b 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -108,6 +108,8 @@ Calls
    Like :meth:`call_soon`, but thread safe.
 
 
+.. _asyncio-delayed-calls:
+
 Delayed calls
 -------------
 
@@ -116,6 +118,20 @@ Which clock is used depends on the (platform-specific) event loop
 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 @@ Run subprocesses asynchronously using the :mod:`subprocess` module.
 
    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
index 9bdf1c1..cfad0bc 100644
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -441,6 +441,9 @@ Task functions
    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.