[Python-checkins] r80679 - peps/trunk/pep-3148.txt

[georg.brandl]

Author: georg.brandl
Date: Sat May  1 11:40:47 2010
New Revision: 80679

Log:
Apply updates sent to PEPs list by Brian Quinlan.

Modified:
   peps/trunk/pep-3148.txt

Modified: peps/trunk/pep-3148.txt
==============================================================================
--- peps/trunk/pep-3148.txt	(original)
+++ peps/trunk/pep-3148.txt	Sat May  1 11:40:47 2010
@@ -149,6 +149,9 @@
 passed to `ProcessPoolExecutor.submit` must be serializeable according to the
 same limitations as the multiprocessing module.
 
+Calling `Executor` or `Future` methods from within a callable submitted to a
+`ProcessPoolExecutor` will result in deadlock.
+
 `__init__(max_workers)`
 
 Executes calls asynchronously using a pool of a most *max_workers*
@@ -215,11 +218,11 @@
 
 Return `True` if the call was successfully cancelled.
 
-`Future.running()`
+`running()`
 
 Return `True` if the call is currently being executed and cannot be cancelled.
 
-`Future.done()`
+`done()`
 
 Return `True` if the call was successfully cancelled or finished running.
 
@@ -248,6 +251,25 @@
 
 If the call completed without raising then ``None`` is returned.
 
+`add_done_callback(fn)`
+
+Attaches a function *fn* to the future that will be called when the future is
+cancelled or finishes running. *fn* will be called with the future as its only
+argument.
+
+If the future has already completed or been cancelled then *fn* will be called
+immediately. If the same function is added several times then it will still only
+be called once.
+
+NOTE: This method can be used to create adapters from Futures to Twisted
+Deferreds.
+
+`remove_done_callback(fn)`
+
+Removes the function *fn*, which was previously attached to the future using
+`add_done_callback`. `KeyError` is raised if the function was not previously
+attached.
+
 Internal Future Methods
 ^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -284,14 +306,10 @@
 
 `wait(fs, timeout=None, return_when=ALL_COMPLETED)`
 
-Wait for the `Future` instances in the given sequence to complete. Returns a
-named 2-tuple of sets. The first set, named "finished", contains the futures
-that completed (finished  or were cancelled) before the wait completed. The
-second set, named "not_finished", contains uncompleted futures.
-
-This method should always be called using keyword arguments, which are:
-
-*fs* is the sequence of Future instances that should be waited on.
+Wait for the `Future` instances given by *fs* to complete. Returns a named
+2-tuple of sets. The first set, named "finished", contains the futures that
+completed (finished  or were cancelled) before the wait completed. The second
+set, named "not_finished", contains uncompleted futures.
 
 *timeout* can be used to control the maximum number of seconds to wait before
 returning. If timeout is not specified or None then there is no limit to the
@@ -313,11 +331,11 @@
 
 `as_completed(fs, timeout=None)`
 
-Returns an iterator over the Future instances given by *fs* that yields futures
-as they complete (finished or were cancelled). Any futures that completed
-before `as_completed()` was called will be yielded first. The returned iterator
-raises a `TimeoutError` if `__next__()` is called and the result isn't available
-after *timeout* seconds from the original call to `as_completed()`. If
+Returns an iterator over the `Future` instances given by *fs* that yields
+futures as they complete (finished or were cancelled). Any futures that
+completed before `as_completed()` was called will be yielded first. The returned
+iterator raises a `TimeoutError` if `__next__()` is called and the result isn't
+available after *timeout* seconds from the original call to `as_completed()`. If
 *timeout* is not specified or `None` then there is no limit to the wait time.
 
 =========
@@ -351,13 +369,14 @@
 operation is eagerly evaluated asynchronously, and execution would only
 block if the proxy object were used before the operation completed.
 
-Anh Hai Trinh proposed a simpler but more limited API concept [5]_.
+Anh Hai Trinh proposed a simpler but more limited API concept [5]_ and the API
+has been discussed in some detail on stdlib-sig [6]_.
 
 ========================
 Reference Implementation
 ========================
 
-The reference implementation [6]_ contains a complete implementation of the
+The reference implementation [7]_ contains a complete implementation of the
 proposed design. It has been tested on Linux and Mac OS X.
 
 ==========
@@ -385,6 +404,10 @@
    `http://www.mail-archive.com/stdlib-sig@python.org/msg00480.html`
 
 .. [6]
+   A discussion of the proposed API on stdlib-sig
+   `http://mail.python.org/pipermail/stdlib-sig/2009-November/000731.html`
+
+.. [7]
    Reference `futures` implementation
    `http://code.google.com/p/pythonfutures/source/browse/#svn/branches/feedback`