Update to PEP 3148 by Jeffrey Yasskin.

pep-3148.txt

@@ -84,12 +84,13 @@ Web Crawl Example
         future_to_url = dict((executor.submit(load_url, url, 60), url)
                              for url in URLS)
 
-    for future in futures.as_completed(future_to_url):
-        url = future_to_url[future]
-        if future.exception() is not None:
-            print('%r generated an exception: %s' % (url, future.exception()))
-        else:
-            print('%r page is %d bytes' % (url, len(future.result())))
+        for future in futures.as_completed(future_to_url):
+            url = future_to_url[future]
+            if future.exception() is not None:
+                print('%r generated an exception: %s' % (url,
+                                                         future.exception()))
+            else:
+                print('%r page is %d bytes' % (url, len(future.result())))
 
 Interface
 ---------
@@ -110,6 +111,8 @@ asynchronously.
 Schedules the callable to be executed as fn(*\*args*, *\*\*kwargs*) and returns
 a `Future` instance representing the execution of the function.
 
+This is an abstract method and must be implemented by Executor subclasses.
+
 `map(func, *iterables, timeout=None)`
 
 Equivalent to map(*func*, *\*iterables*) but executed asynchronously and
@@ -158,6 +161,40 @@ ThreadPoolExecutor
 The `ThreadPoolExecutor` class is an `Executor` subclass that uses a pool of
 threads to execute calls asynchronously.
 
+Deadlock can occur when the callable associated with a `Future` waits on
+the results of another `Future`. For example:
+
+::
+
+    import time
+    def wait_on_b():
+        time.sleep(5)
+        print(b.result())  # b will never complete because it is waiting on a.
+        return 5
+
+    def wait_on_a():
+        time.sleep(5)
+        print(a.result())  # a will never complete because it is waiting on b.
+        return 6
+
+
+    executor = ThreadPoolExecutor(max_workers=2)
+    a = executor.submit(wait_on_b)
+    b = executor.submit(wait_on_a)
+
+And:
+
+::
+
+    def wait_on_future():
+        f = executor.submit(pow, 5, 2)
+        # This will never complete because there is only one worker thread and
+        # it is executing this function.
+        print(f.result())
+    
+    executor = ThreadPoolExecutor(max_workers=1)
+    executor.submit(wait_on_future)
+
 `__init__(max_workers)`
 
 Executes calls asynchronously using a pool of at most *max_workers* threads.
@@ -178,6 +215,10 @@ will be cancelled and the method will return `True`.
 
 Return `True` if the call was successfully cancelled.
 
+`Future.running()`
+
+Return `True` if the call is currently being executed and cannot be cancelled.
+
 `Future.done()`
 
 Return `True` if the call was successfully cancelled or finished running.
@@ -207,6 +248,37 @@ be raised.
 
 If the call completed without raising then ``None`` is returned.
 
+Internal Future Methods
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The following `Future` methods are meant for use in unit tests and `Executor`
+implementations.
+
+`set_running_or_notify_cancel()`
+
+Should be called by `Executor` implementations before executing the work
+associated with the `Future`.
+
+If the method returns `False` then the `Future` was cancelled i.e.
+`Future.cancel` was called and returned `True`. Any threads waiting on the
+`Future` completing (i.e. through `as_completed()` or `wait()`) will be woken
+up.
+
+If the method returns `True` then the `Future` was not cancelled and has been
+put in the running state i.e. calls to `Future.running()` will return `True`.
+
+This method can only be called once and cannot be called after
+`Future.set_result()` or `Future.set_exception()` have been called.
+
+`set_result(result)`
+
+Sets the result of the work associated with the `Future`.
+
+`set_exception(exception)`
+
+Sets the result of the work associated with the `Future` to the given
+`Exception`.
+   
 Module Functions
 ''''''''''''''''
 
@@ -313,7 +385,8 @@ References
    `http://www.mail-archive.com/stdlib-sig@python.org/msg00480.html`
 
 .. [6]
-   Reference `futures` implementation `http://code.google.com/p/pythonfutures`
+   Reference `futures` implementation
+   `http://code.google.com/p/pythonfutures/source/browse/#svn/branches/feedback`
 
 =========
 Copyright