[Python-checkins] cpython (3.4): asyncio doc: add a section about task cancellation

victor.stinner python-checkins at python.org
Fri Jan 30 00:56:20 CET 2015


https://hg.python.org/cpython/rev/173d4a8e1e74
changeset:   94387:173d4a8e1e74
branch:      3.4
parent:      94385:21010940f8c1
user:        Victor Stinner <victor.stinner at gmail.com>
date:        Fri Jan 30 00:55:58 2015 +0100
summary:
  asyncio doc: add a section about task cancellation

files:
  Doc/library/asyncio-dev.rst |  37 +++++++++++++++++++++++++
  1 files changed, 37 insertions(+), 0 deletions(-)


diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst
--- a/Doc/library/asyncio-dev.rst
+++ b/Doc/library/asyncio-dev.rst
@@ -40,6 +40,43 @@
    <asyncio-logger>`.
 
 
+Cancellation
+------------
+
+Cancellation of tasks is not common in classic programming. In asynchronous
+programming, not only it is something common, but you have to prepare your
+code to handle it.
+
+Futures and tasks can be cancelled explicitly with their :meth:`Future.cancel`
+method. The :func:`wait_for` function cancels the waited task when the timeout
+occurs. There are many other cases where a task can be cancelled indirectly.
+
+Don't call :meth:`~Future.set_result` or :meth:`~Future.set_exception` method
+of :class:`Future` if the future is cancelled: it would fail with an exception.
+For example, write::
+
+    if not fut.cancelled():
+        fut.set_result('done')
+
+Don't schedule directly a call to the :meth:`~Future.set_result` or the
+:meth:`~Future.set_exception` method of a future with
+:meth:`BaseEventLoop.call_soon`: the future can be cancelled before its method
+is called.
+
+If you wait for a future, you should check early if the future was cancelled to
+avoid useless operations. Example::
+
+    @coroutine
+    def slow_operation(fut):
+        if fut.cancelled():
+            return
+        # ... slow computation ...
+        yield from fut
+        # ...
+
+The :func:`shield` function can also be used to ignore cancellation.
+
+
 .. _asyncio-multithreading:
 
 Concurrency and multithreading

-- 
Repository URL: https://hg.python.org/cpython


More information about the Python-checkins mailing list