[Python-checkins] cpython (3.4): asyncio: Document Task.cancel() properly.

[victor.stinner]

http://hg.python.org/cpython/rev/027568b52a06
changeset:   90163:027568b52a06
branch:      3.4
parent:      90161:d1d4bcf87e59
user:        Victor Stinner <victor.stinner at gmail.com>
date:        Mon Apr 07 11:18:06 2014 +0200
summary:
  asyncio: Document Task.cancel() properly.

files:
  Lib/asyncio/tasks.py |  19 +++++++++++++++++++
  1 files changed, 19 insertions(+), 0 deletions(-)


diff --git a/Lib/asyncio/tasks.py b/Lib/asyncio/tasks.py
--- a/Lib/asyncio/tasks.py
+++ b/Lib/asyncio/tasks.py
@@ -250,6 +250,25 @@
                 print(line, file=file, end='')
 
     def cancel(self):
+        """Request that a task to cancel itself.
+
+        This arranges for a CancellationError to be thrown into the
+        wrapped coroutine on the next cycle through the event loop.
+        The coroutine then has a chance to clean up or even deny
+        the request using try/except/finally.
+
+        Contrary to Future.cancel(), this does not guarantee that the
+        task will be cancelled: the exception might be caught and
+        acted upon, delaying cancellation of the task or preventing it
+        completely.  The task may also return a value or raise a
+        different exception.
+
+        Immediately after this method is called, Task.cancelled() will
+        not return True (unless the task was already cancelled).  A
+        task will be marked as cancelled when the wrapped coroutine
+        terminates with a CancelledError exception (even if cancel()
+        was not called).
+        """
         if self.done():
             return False
         if self._fut_waiter is not None:

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