1Advanced event loops 2==================== 3 4libuv provides considerable user control over event loops, and you can achieve 5interesting results by juggling multiple loops. You can also embed libuv's 6event loop into another event loop based library -- imagine a Qt based UI, and 7Qt's event loop driving a libuv backend which does intensive system level 8tasks. 9 10Stopping an event loop 11~~~~~~~~~~~~~~~~~~~~~~ 12 13``uv_stop()`` can be used to stop an event loop. The earliest the loop will 14stop running is *on the next iteration*, possibly later. This means that events 15that are ready to be processed in this iteration of the loop will still be 16processed, so ``uv_stop()`` can't be used as a kill switch. When ``uv_stop()`` 17is called, the loop **won't** block for i/o on this iteration. The semantics of 18these things can be a bit difficult to understand, so let's look at 19``uv_run()`` where all the control flow occurs. 20 21.. rubric:: src/unix/core.c - uv_run 22.. literalinclude:: ../../../src/unix/core.c 23 :language: c 24 :linenos: 25 :lines: 304-324 26 :emphasize-lines: 10,19,21 27 28``stop_flag`` is set by ``uv_stop()``. Now all libuv callbacks are invoked 29within the event loop, which is why invoking ``uv_stop()`` in them will still 30lead to this iteration of the loop occurring. First libuv updates timers, then 31runs pending timer, idle and prepare callbacks, and invokes any pending I/O 32callbacks. If you were to call ``uv_stop()`` in any of them, ``stop_flag`` 33would be set. This causes ``uv_backend_timeout()`` to return ``0``, which is 34why the loop does not block on I/O. If on the other hand, you called 35``uv_stop()`` in one of the check handlers, I/O has already finished and is not 36affected. 37 38``uv_stop()`` is useful to shutdown a loop when a result has been computed or 39there is an error, without having to ensure that all handlers are stopped one 40by one. 41 42Here is a simple example that stops the loop and demonstrates how the current 43iteration of the loop still takes places. 44 45.. rubric:: uvstop/main.c 46.. literalinclude:: ../../code/uvstop/main.c 47 :language: c 48 :linenos: 49 :emphasize-lines: 11 50 51
