[Python-checkins] peps: Clarify motivation for serializing callbacks.

[guido.van.rossum]

http://hg.python.org/peps/rev/d73d5861333b
changeset:   5158:d73d5861333b
user:        Guido van Rossum <guido at dropbox.com>
date:        Tue Oct 01 08:37:33 2013 -0700
summary:
  Clarify motivation for serializing callbacks.

files:
  pep-3156.txt |  18 ++++++++++++------
  1 files changed, 12 insertions(+), 6 deletions(-)


diff --git a/pep-3156.txt b/pep-3156.txt
--- a/pep-3156.txt
+++ b/pep-3156.txt
@@ -362,13 +362,17 @@
 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 @@
   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

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