You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/source/reference-core.rst
+5-5Lines changed: 5 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -667,7 +667,7 @@ In Trio, child tasks inherit the parent nursery's cancel scopes. So in
667
667
this example, both the child tasks will be cancelled when the timeout
668
668
expires::
669
669
670
-
with move_on_after(TIMEOUT):
670
+
with trio.move_on_after(TIMEOUT):
671
671
async with trio.open_nursery() as nursery:
672
672
nursery.start_soon(child1)
673
673
nursery.start_soon(child2)
@@ -678,12 +678,12 @@ Note that what matters here is the scopes that were active when
678
678
nothing at all::
679
679
680
680
async with trio.open_nursery() as nursery:
681
-
with move_on_after(TIMEOUT): # don't do this!
681
+
with trio.move_on_after(TIMEOUT): # don't do this!
682
682
nursery.start_soon(child)
683
683
684
-
Why is this so? Well, ``start_soon()`` returns as soon as it has scheduled the new task to start running. The flow of execution in the parent then continues on to exit the ``with move_on_after(TIMEOUT):`` block, at which point Trio forgets about the timeout entirely. In order for the timeout to apply to the child task, Trio must be able to tell that its associated cancel scope will stay open for at least as long as the child task is executing. And Trio can only know that for sure if the cancel scope block is outside the nursery block.
684
+
Why is this so? Well, ``start_soon()`` returns as soon as it has scheduled the new task to start running. The flow of execution in the parent then continues on to exit the ``with trio.move_on_after(TIMEOUT):`` block, at which point Trio forgets about the timeout entirely. In order for the timeout to apply to the child task, Trio must be able to tell that its associated cancel scope will stay open for at least as long as the child task is executing. And Trio can only know that for sure if the cancel scope block is outside the nursery block.
685
685
686
-
You might wonder why Trio can't just remember "this task should be cancelled in ``TIMEOUT`` seconds", even after the ``with move_on_after(TIMEOUT):`` block is gone. The reason has to do with :ref:`how cancellation is implemented <cancellation>`. Recall that cancellation is represented by a `Cancelled` exception, which eventually needs to be caught by the cancel scope that caused it. (Otherwise, the exception would take down your whole program!) In order to be able to cancel the child tasks, the cancel scope has to be able to "see" the `Cancelled` exceptions that they raise -- and those exceptions come out of the ``async with open_nursery()`` block, not out of the call to ``start_soon()``.
686
+
You might wonder why Trio can't just remember "this task should be cancelled in ``TIMEOUT`` seconds", even after the ``with trio.move_on_after(TIMEOUT):`` block is gone. The reason has to do with :ref:`how cancellation is implemented <cancellation>`. Recall that cancellation is represented by a `Cancelled` exception, which eventually needs to be caught by the cancel scope that caused it. (Otherwise, the exception would take down your whole program!) In order to be able to cancel the child tasks, the cancel scope has to be able to "see" the `Cancelled` exceptions that they raise -- and those exceptions come out of the ``async with open_nursery()`` block, not out of the call to ``start_soon()``.
687
687
688
688
If you want a timeout to apply to one task but not another, then you need to put the cancel scope in that individual task's function -- ``child()``, in this example.
689
689
@@ -763,7 +763,7 @@ example, the timeout does *not* apply to ``child`` (or to anything
763
763
else)::
764
764
765
765
async def do_spawn(nursery):
766
-
with move_on_after(TIMEOUT): # don't do this, it has no effect
766
+
with trio.move_on_after(TIMEOUT): # don't do this, it has no effect
0 commit comments