From: Victor Stinner Date: Mon, 7 Apr 2014 09:18:06 +0000 (+0200) Subject: asyncio: Document Task.cancel() properly. X-Git-Tag: v3.4.1rc1~123 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=4bd652a276c575de476d634da8cc4f95815721e9;p=python asyncio: Document Task.cancel() properly. --- diff --git a/Lib/asyncio/tasks.py b/Lib/asyncio/tasks.py index 0967e7e628..153f731a76 100644 --- a/Lib/asyncio/tasks.py +++ b/Lib/asyncio/tasks.py @@ -250,6 +250,25 @@ class Task(futures.Future): 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: