[Python-checkins] cpython (merge 3.4 -> default): (Merge 3.4) Issue #21601: Document asyncio.Task.cancel(). Initial patch written
victor.stinner
python-checkins at python.org
Mon Jun 2 23:09:07 CEST 2014
http://hg.python.org/cpython/rev/0ee47d3d2664
changeset: 90986:0ee47d3d2664
parent: 90984:118e427808ce
parent: 90985:c2384ca7fc3b
user: Victor Stinner <victor.stinner at gmail.com>
date: Mon Jun 02 23:08:52 2014 +0200
summary:
(Merge 3.4) Issue #21601: Document asyncio.Task.cancel(). Initial patch written
by Vajrasky Kok.
files:
Doc/library/asyncio-task.rst | 22 +++++++++++++++++++++-
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
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -327,7 +327,27 @@
``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
--- a/Lib/asyncio/tasks.py
+++ b/Lib/asyncio/tasks.py
@@ -269,9 +269,9 @@
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.
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list