[Python-checkins] peps: Remove @task; add gather(); remote run_until_complete() timeout; some wording

[guido.van.rossum]

http://hg.python.org/peps/rev/aabbd1324891
changeset:   5104:aabbd1324891
user:        Guido van Rossum <guido at python.org>
date:        Sun Sep 08 19:11:55 2013 -0700
summary:
  Remove @task; add gather(); remote run_until_complete() timeout; some wording cleanup.

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


diff --git a/pep-3156.txt b/pep-3156.txt
--- a/pep-3156.txt
+++ b/pep-3156.txt
@@ -334,13 +334,10 @@
   and in part because there shouldn't be many places where this is
   called anyway.)
 
-- ``run_until_complete(future, timeout=None)``.  Runs the event loop
-  until the 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, or if ``stop()`` is called, ``TimeoutError`` is raised (but
-  the Future is not cancelled).  This cannot be called when the event
-  loop is already running.
+- ``run_until_complete(future)``.  Runs the event loop until the
+  Future is done.  If the Future is done, its result is returned, or
+  its exception is raised.  This cannot be called when the event loop
+  is already running.
 
 - ``stop()``.  Stops the event loop as soon as it is convenient.  It
   is fine to restart the loop with ``run_forever()`` or
@@ -1301,14 +1298,14 @@
   ``FIRST_COMPLETED``, ``FIRST_EXCEPTION``, ``ALL_COMPLETED`` are
   defined with the same values and the same meanings as in PEP 3148:
 
-  - ``ALL_COMPLETED`` (default): Wait until all Futures are done or
-    completed (or until the timeout occurs).
+  - ``ALL_COMPLETED`` (default): Wait until all Futures are done (or
+    until the timeout occurs).
 
-  - ``FIRST_COMPLETED``: Wait until at least one Future is done or
-    cancelled (or until the timeout occurs).
+  - ``FIRST_COMPLETED``: Wait until at least one Future is done (or
+    until the timeout occurs).
 
-  - ``FIRST_EXCEPTION``: Wait until at least one Future is done (not
-    cancelled) with an exception set.  (The exclusion of cancelled
+  - ``FIRST_EXCEPTION``: Wait until at least one Future is done but
+    not cancelled with an exception set.  (The exclusion of cancelled
     Futures from the condition is surprising, but PEP 3148 does it
     this way.)
 
@@ -1335,6 +1332,16 @@
   returning the result or raising the exception if it is completed
   within the timeout, raising ``TimeoutError`` otherwise.
 
+- ``tulip.gather(f1, f2, ...)``.  Returns a Future which waits until
+  all arguments (Futures or coroutines) are done and return a list of
+  their corresponding results.  If one or more of the arguments is
+  cancelled or raises an exception, the returned Future is cancelled
+  or has its exception set (matching what happened to the first
+  argument), and the remaining arguments are left running in the
+  background.  Cancelling the returned Future does not affect the
+  arguments.  Note that coroutine arguments are converted to Futures
+  using ``tulip.async()``.
+
 Sleeping
 --------
 
@@ -1363,11 +1370,9 @@
 callback-based frameworks like Twisted.  After converting a coroutine
 into a Task, callbacks can be added to the Task.
 
-There are two ways to convert a coroutine into a task: explicitly, by
-calling the coroutine function and then passing the resulting
-coroutine object to the ``tulip.Task()`` constructor; or implicitly,
-by decorating the coroutine with ``@tulip.task`` (instead of
-``@tulip.coroutine``).
+To convert a coroutine into a task, call the coroutine function and
+pass the resulting coroutine object to the ``tulip.Task()``
+constructor.  You may also use ``tulip.async()`` for this purpose.
 
 You may ask, why not automatically convert all coroutines to Tasks?
 The ``@tulip.coroutine`` decorator could do this.  However, this would

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