[Python-checkins] peps: Spec out Future better.

[guido.van.rossum]

http://hg.python.org/peps/rev/2fc65f2161ca
changeset:   4662:2fc65f2161ca
user:        Guido van Rossum <guido at python.org>
date:        Wed Jan 09 11:58:51 2013 -0800
summary:
  Spec out Future better.

files:
  pep-3156.txt |  90 ++++++++++++++++++++++++++++------------
  1 files changed, 63 insertions(+), 27 deletions(-)


diff --git a/pep-3156.txt b/pep-3156.txt
--- a/pep-3156.txt
+++ b/pep-3156.txt
@@ -276,8 +276,7 @@
   whose result on success is the return value that call.  This is
   equivalent to ``wrap_future(executor.submit(callback, *args))``.  If
   ``executor`` is ``None``, a default ``ThreadPoolExecutor`` with 5
-  threads is used.  (TBD: Should the default executor be shared
-  between different event loops?)
+  threads is used.
 
 - ``set_default_executor(executor)``.  Set the default executor used
   by ``run_in_executor()``.
@@ -515,39 +514,76 @@
 
 The ``tulip.Future`` class here is intentionally similar to the
 ``concurrent.futures.Future`` class specified by PEP 3148, but there
-are slight differences.  The supported public API is as follows,
-indicating the differences with PEP 3148:
+are slight differences.  Whenever this PEP talks about Futures or
+futures this should be understood to refer to ``tulip.Future`` unless
+``concurrent.futures.Future`` is explicitly mentioned.  The supported
+public API is as follows, indicating the differences with PEP 3148:
 
-- ``cancel()``.
-  TBD: Exact specification.
+- ``cancel()``.  If the Future is already done (or cancelled), return
+  ``False``.  Otherwise, change the Future's state to cancelled (this
+  implies done), schedule the callbacks, and return ``True``.
 
-- ``cancelled()``.
+- ``cancelled()``.  Returns ``True`` if the Future was cancelled.
 
-- ``running()``.  Note that the meaning of this method is essentially
-  "cannot be cancelled and isn't done yet".  (TBD: Would be nice if
-  this could be set *and* cleared in some cases, e.g. sock_recv().)
+- ``running()``.  Always returns ``False``.  Difference with PEP 3148:
+  there is no "running" state.
 
-- ``done()``.
+- ``done()``.  Returns ``True`` if the Future is done.  Note that a
+  cancelled Future is considered done too (here and everywhere).
 
-- ``result()``.  Difference with PEP 3148: This has no timeout
-  argument and does *not* wait; if the future is not yet done, it
-  raises an exception.
+- ``result()``.  Returns the result set with ``set_result()``, or
+  raises the exception set with ``set_exception()``.  Raises
+  ``CancelledError`` if cancelled.  Difference with PEP 3148: This has
+  no timeout argument and does *not* wait; if the future is not yet
+  done, it raises an exception.
 
-- ``exception()``.  Difference with PEP 3148: This has no timeout
-  argument and does *not* wait; if the future is not yet done, it
-  raises an exception.
+- ``exception()``.  Returns the exception if set with
+  ``set_exception()``, or ``None`` if a result was set with
+  ``set_result()``.  Raises ``CancelledError`` if cancelled.
+  Difference with PEP 3148: This has no timeout argument and does
+  *not* wait; if the future is not yet done, it raises an exception.
 
-- ``add_done_callback(fn)``.  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 ``call_soon_threadsafe()``.  Note
-  that 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.
+- ``add_done_callback(fn)``.  Add a callback to be run when the Future
+  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
+  ``call_soon()``.  Note that 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, and should not be a Handler object.
 
-The internal methods defined in PEP 3148 are not supported.  (TBD:
-Maybe we do need to support these, in order to make it easy to write
-user code that returns a Future?)
+- ``set_result(result)``.  The Future must not be done (nor cancelled)
+  already.  This makes the Future done and schedules the callbacks.
+  Difference with PEP 3148: This is a public API.
+
+- ``set_exception(exception)``.  The Future must not be done (nor
+  cancelled) already.  This makes the Future done and schedules the
+  callbacks.  Difference with PEP 3148: This is a public API.
+
+The internal method ``set_running_or_notify_cancel()`` is not
+supported; there is no way to set the running state.
+
+The following exceptions are defined:
+
+- ``InvalidStateError``.  Raised whenever the Future is not in a state
+  acceptable to the method being called (e.g. calling ``set_result()``
+  on a Future that is already done, or calling ``result()`` on a Future
+  that is not yet done).
+
+- ``InvalidTimeoutError``.  Raised by ``result()`` and ``exception()``
+  when a nonzero ``timeout`` argument is given.
+
+- ``CancelledError``.  An alias for
+  ``concurrent.futures.CancelledError``.  Raised when ``result()`` or
+  ``exception()`` is called on a Future that is cancelled.
+
+- ``TimeoutError``.  An alias for ``concurrent.futures.TimeoutError``.
+  May be raised by ``EventLoop.run_until_complete()``.
+
+A Future is associated with the default event loop when it is created.
+(TBD: Optionally pass in an alternative event loop instance?)
 
 A ``tulip.Future`` object is not acceptable to the ``wait()`` and
 ``as_completed()`` functions in the ``concurrent.futures`` package.

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