diff --git a/pep-3156.txt b/pep-3156.txt index f69232d22..e75672cda 100644 --- a/pep-3156.txt +++ b/pep-3156.txt @@ -362,13 +362,17 @@ stopped. These methods deal with starting and stopping an event loop: Basic Callbacks ''''''''''''''' +Callbacks associated with the same event loop are strictly serialized: +one callback must finish before the next one will be called. This is +an important guarantee: when two or more callbacks use or modify +shared state, each callback is guaranteed that while is running, the +shared state isn't changed by another callback. + - ``call_soon(callback, *args)``. This schedules a callback to be called as soon as possible. Returns a Handle representing the callback, whose ``cancel()`` method can be used to cancel the callback. It guarantees that callbacks are called in the order in - which they were scheduled. Callbacks associated with the same event - loop are strictly serialized -- one callback must exit before the - next one will be called. + which they were scheduled. - ``call_later(delay, callback, *args)``. Arrange for ``callback(*args)`` to be called approximately ``delay`` seconds in @@ -842,12 +846,14 @@ public API is as follows, indicating the differences with PEP 3148: becomes done (or is cancelled). If the Future is already done (or cancelled), schedules the callback to using ``call_soon()``. Difference with PEP 3148: The callback is never called immediately, - and always in the context of the caller. (Typically, a context is a - thread.) You can think of this as calling the callback through + and always in the context of the caller -- typically this is a + thread. You can think of this as calling the callback through ``call_soon()``. Note that in order to match PEP 3148, the callback (unlike all other callbacks defined in this PEP, and ignoring the convention from the section "Callback Style" below) is always called - with a single argument, the Future object. + with a single argument, the Future object. (The motivation for + strictly serializing callbacks scheduled with ``call_soon()`` + applies here too.) - ``remove_done_callback(fn)``. Remove the argument from the list of callbacks. This method is not defined by PEP 3148. The argument