win,unix: change execution order of timers (#3927)

The maximum number of times timers should run when uv_run() is called
with UV_RUN_ONCE and UV_RUN_NOWAIT is 1. Do that by conditionally
calling timers before entering the while loop when called with
UV_RUN_DEFAULT.

The reason to always run timers at the end of the while loop, instead of
at the beginning, is to help enforce the conceptual event loop model.
Which starts when entering the event provider (e.g. calling poll).

Other than only allowing timers to be processed once per uv_run()
execution, the only other noticeable change this will show is if all the
following are true:
* uv_run() is called with UV_RUN_NOWAIT or UV_RUN_ONCE.
* An event is waiting to be received when poll is called.
* Execution time between the call to uv_timer_start() and entering the
  while loop is longer than the timeout.

If all these are true, then timers that would have executed before
entering the event provider will now be executed afterward.

Fixes: https://github.com/libuv/libuv/issues/3686
Co-authored-by: Momtchil Momtchev <momtchil@momtchev.com>

2 files changed, 9 insertions, 8 deletions

diff --git a/docs/src/design.rst b/docs/src/design.rst
index 0f5580c7..5a20595c 100644
--- a/docs/src/design.rst
+++ b/docs/src/design.rst
@@ -60,16 +60,15 @@ stages of a loop iteration:
     :align: center
 
 
-#. The loop concept of 'now' is updated. The event loop caches the current time at the start of
-   the event loop tick in order to reduce the number of time-related system calls.
+#. The loop concept of 'now' is initially set.
+
+#. Due timers are run if the loop was run with ``UV_RUN_DEFAULT``. All active timers scheduled
+   for a time before the loop's concept of *now* get their callbacks called.
 
 #. If the loop is *alive*  an iteration is started, otherwise the loop will exit immediately. So,
    when is a loop considered to be *alive*? If a loop has active and ref'd handles, active
    requests or closing handles it's considered to be *alive*.
 
-#. Due timers are run. All active timers scheduled for a time before the loop's concept of *now*
-   get their callbacks called.
-
 #. Pending callbacks are called. All I/O callbacks are called right after polling for I/O, for the
    most part. There are cases, however, in which calling such a callback is deferred for the next
    loop iteration. If the previous iteration deferred any I/O callback it will be run at this point.
@@ -101,9 +100,11 @@ stages of a loop iteration:
 #. Close callbacks are called. If a handle was closed by calling :c:func:`uv_close` it will
    get the close callback called.
 
-#. Special case in case the loop was run with ``UV_RUN_ONCE``, as it implies forward progress.
-   It's possible that no I/O callbacks were fired after blocking for I/O, but some time has passed
-   so there might be timers which are due, those timers get their callbacks called.
+#. The loop concept of 'now' is updated.
+
+#. Due timers are run. Note that 'now' is not updated again until the next loop iteration.
+   So if a timer became due while other timers were being processed, it won't be run until
+   the following event loop iteration.
 
 #. Iteration ends. If the loop was run with ``UV_RUN_NOWAIT`` or ``UV_RUN_ONCE`` modes the
    iteration ends and :c:func:`uv_run` will return. If the loop was run with ``UV_RUN_DEFAULT``
diff --git a/docs/src/static/loop_iteration.png b/docs/src/static/loop_iteration.png
index e769cf33..1545f84a 100644
--- a/docs/src/static/loop_iteration.png
+++ b/docs/src/static/loop_iteration.png