[Python-checkins] peps: Add stop(), run_once(), run_until_complete(), call_repeatedly().

[guido.van.rossum]

http://hg.python.org/peps/rev/842c42cfd1c7
changeset:   4622:842c42cfd1c7
user:        Guido van Rossum <guido at google.com>
date:        Wed Dec 19 09:59:50 2012 -0800
summary:
  Add stop(), run_once(), run_until_complete(), call_repeatedly().
Rename DelayedCall to Handler.

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


diff --git a/pep-3156.txt b/pep-3156.txt
--- a/pep-3156.txt
+++ b/pep-3156.txt
@@ -169,22 +169,46 @@
 
   Note: run() blocks until the termination condition is met.
 
-  TBD: run() may need an argument to start some work?
+- ``stop()``.  Stops the event loop as soon as it is convenient.  It
+  is fine to restart the loop with ``run()`` (or one of its variants)
+  subsequently.  (TBD: How should this interact with ``run_once()``
+  and ``run_until_complete()``?)
 
-- TBD: Do we need an API for stopping the event loop, given that we
-  have the termination condition?  Is the termination condition
-  compatible with other frameworks?
+  Note: How soon exactly is up to the implementation.  It is
+  reasonable to implement this so that ``run()`` simply stops calling
+  ``run_once()`` when this is called.
 
-- TBD: Do we need an API to run the event loop for a little while
-  (e.g.  a single iteration)?  If so, exactly what should it do?
+- ``run_until_complete(future, timeout=None)``.  Runs the event loop
+  until a Future is done.  If a timeout is given, it waits at most
+  that long.  If the Future is done, its result is returned, or its
+  exception is raised; if the timeout expires before the Future is
+  done, TimeoutError is raised (but the Future is not cancelled).
+  This cannot be called when the event loop is already running.
+  
+  Note: This API is most useful for tests and the like.  It should not
+  be used as a substitute for ``yield from future`` or other ways to
+  wait for a Future (e.g. registering a done callback).
+
+- ``run_once(timeout=None)``.  Run the event loop for a little while.
+  If a timeout is given, an I/O poll will be given at most that timeout;
+  otherwise, an I/O poll is not constrained in time.
+
+  Note: Exactlly what this does is up to the implementation.  One
+  constraint: if a callback immediately schedules itself using
+  ``call_soon()``, ``run_once()`` should still return.
 
 - ``call_later(delay, callback, *args)``.  Arrange for
   ``callback(*args)`` to be called approximately ``delay`` seconds in
   the future, once, unless canceled.  As usual in Python, ``delay`` may
   be a floating point number to represent smaller intervals.  Returns
-  a ``DelayedCall`` object representing the callback, whose
+  a ``Handler`` object representing the callback, whose
   ``cancel()`` method can be used to cancel the callback.
 
+- ``call_repeatedly(interval, callback, **args)``.  Like ``call_later()``
+  but calls the callback repeatedly, every ``interval`` seconds,
+  until the ``Handler`` returned is cancelled.  The first call is in
+  ``interval`` seconds.  May be a float.
+
 - ``call_soon(callback, *args)``.  Equivalent to ``call_later(0,
   callback, *args)``.
 
@@ -197,8 +221,8 @@
   ``ev.call_soon_threadsafe(ev.call_later, when, callback, *args)``.)
 
 - TBD: A way to register a callback that is already wrapped in a
-  ``DelayedCall``.  Maybe ``call_soon()`` could just check
-  ``isinstance(callback, DelayedCall)``?  It should silently skip
+  ``Handler``.  Maybe ``call_soon()`` could just check
+  ``isinstance(callback, Handler)``?  It should silently skip
   a canceled callback.
 
 - TBD: Repeatable timers.
@@ -287,12 +311,12 @@
 
 - ``add_reader(fd, callback, *args)``.  Arrange for
   ``callback(*args)`` to be called whenever file descriptor ``fd`` is
-  ready for reading.  Returns a ``DelayedCall`` object which can be
+  ready for reading.  Returns a ``Handler`` object which can be
   used to cancel the callback.  Note that, unlike ``call_later()``,
   the callback may be called many times.  Calling ``add_reader()``
   again for the same file descriptor implicitly cancels the previous
   callback for that file descriptor.  (TBD: Returning a
-  ``DelayedCall`` that can be cancelled seems awkward.  Let's forget
+  ``Handler`` that can be cancelled seems awkward.  Let's forget
   about that.)  (TBD: Change this to raise an exception if a handler
   is already set.)
 
@@ -303,7 +327,7 @@
   descriptor ``fd``, if one is set.  A no-op if no callback is
   currently set for the file descriptor.  (The reason for providing
   this alternate interface is that it is often more convenient to
-  remember the file descriptor than to remember the ``DelayedCall``
+  remember the file descriptor than to remember the ``Handler``
   object.)  (TBD: Return ``True`` if a handler was removed, ``False``
   if not.)
 
@@ -391,13 +415,13 @@
 and ``SystemExit``; it is usually unwise to treat these the same as
 most other exceptions.)
 
-The DelayedCall Class
----------------------
+The Handler Class
+-----------------
 
 The various methods for registering callbacks (e.g. ``call_later()``)
 all return an object representing the registration that can be used to
 cancel the callback.  For want of a better name this object is called
-a ``DelayedCall``, although the user never needs to instantiate
+a ``Handler``, although the user never needs to instantiate
 instances of this class.  There is one public method:
 
 - ``cancel()``.  Attempt to cancel the callback.
@@ -423,9 +447,6 @@
 TBD: Public attribute recording the realtime value when the callback
 is scheduled?  (Since this is needed anyway for storing it in a heap.)
 
-TBD: A better name for the class?  Reasonable suggestions so far:
-``Callback``, ``Call``, ``Handler`` (my current favorite), ``Thunk``.
-
 Futures
 -------
 

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