From b2ed7b4b06bc92e3e0006555bfd7518ca1134e12 Mon Sep 17 00:00:00 2001 From: "Nathaniel J. Smith" Date: Mon, 12 Feb 2018 21:01:06 -0800 Subject: [PATCH] More edits --- docs/source/reference-core.rst | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/docs/source/reference-core.rst b/docs/source/reference-core.rst index 28ee74d262..89f0c34085 100644 --- a/docs/source/reference-core.rst +++ b/docs/source/reference-core.rst @@ -566,17 +566,21 @@ Cancel scope objects provide the following interface: .. attribute:: cancel_called - Readonly :class:`bool`. Records whether this scope has been - cancelled, either by an explicit call to :meth:`cancel` or by - the deadline expiring. - - .. note:: - - This attribute being True does *not* mean that the code within the - scope has been affected by the cancellation. - - Thus, in most (if not all) cases you should use - :attr:'cancelled_caught` instead. + Readonly :class:`bool`. Records whether cancellation has been + requested for this scope, either by an explicit call to + :meth:`cancel` or by the deadline expiring. + + This attribute being True does *not* necessarily mean that + the code within the scope has been, or will be, affected by + the cancellation. For example, if :meth:`cancel` was called + just before the scope exits, when it's too late to deliver + a :exc:`~trio.Cancelled` exception, then this attribute will + still be True. + + This attribute is mostly useful for debugging and introspection. + If you want to know whether or not a chunk of code was actually + cancelled, then :attr:`cancelled_caught` is usually more + appropriate. Trio also provides several convenience functions for the common situation of just wanting to impose a timeout on some code: