diff options
| -rw-r--r-- | Doc/library/asyncio-task.rst | 22 | ||||
| -rw-r--r-- | Lib/asyncio/tasks.py | 4 |
2 files changed, 23 insertions, 3 deletions
diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index 67eaccd..eb254a9 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -327,7 +327,27 @@ Task ``None`` is returned when called not in the context of a :class:`Task`. - .. method:: get_stack(self, \*, limit=None) + .. method:: cancel() + + Request this task to cancel itself. + + This arranges for a :exc:`~concurrent.futures.CancelledError` 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 :meth:`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, :meth:`~Future.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 + :exc:`~concurrent.futures.CancelledError` exception (even if + :meth:`cancel` was not called). + + .. method:: get_stack(\*, limit=None) Return the list of stack frames for this task's coroutine. diff --git a/Lib/asyncio/tasks.py b/Lib/asyncio/tasks.py index 45a6342..2aa568b 100644 --- a/Lib/asyncio/tasks.py +++ b/Lib/asyncio/tasks.py @@ -269,9 +269,9 @@ class Task(futures.Future): print(line, file=file, end='') def cancel(self): - """Request that a task to cancel itself. + """Request this task to cancel itself. - This arranges for a CancellationError to be thrown into the + This arranges for a CancelledError 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. |