Skip to content

Commit 7e81863

Browse files
committed
Fix doc refs to move_on_after missing trio module qualifier
1 parent dc0e9bc commit 7e81863

File tree

1 file changed

+5
-5
lines changed

1 file changed

+5
-5
lines changed

docs/source/reference-core.rst

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -667,7 +667,7 @@ In Trio, child tasks inherit the parent nursery's cancel scopes. So in
667667
this example, both the child tasks will be cancelled when the timeout
668668
expires::
669669

670-
with move_on_after(TIMEOUT):
670+
with trio.move_on_after(TIMEOUT):
671671
async with trio.open_nursery() as nursery:
672672
nursery.start_soon(child1)
673673
nursery.start_soon(child2)
@@ -678,12 +678,12 @@ Note that what matters here is the scopes that were active when
678678
nothing at all::
679679

680680
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!
682682
nursery.start_soon(child)
683683

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.
685685

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()``.
687687

688688
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.
689689

@@ -763,7 +763,7 @@ example, the timeout does *not* apply to ``child`` (or to anything
763763
else)::
764764

765765
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
767767
nursery.start_soon(child)
768768

769769
async with trio.open_nursery() as nursery:

0 commit comments

Comments
 (0)