Skip to content

Commit a8030d6

Browse files
committed
Rework phrasing around how await tasks pauses and returns control in the await section.
1 parent 7b5ff84 commit a8030d6

1 file changed

Lines changed: 24 additions & 7 deletions

File tree

Doc/howto/a-conceptual-overview-of-asyncio.rst

Lines changed: 24 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -204,14 +204,31 @@ different ways::
204204
In a crucial way, the behavior of ``await`` depends on the type of object
205205
being awaited.
206206

207-
awaiting a task will cede control from the current task or coroutine to
207+
Awaiting a task will cede control from the current task or coroutine to
208208
the event loop.
209-
In the process of relinquishing control, the task that's giving up control
210-
adds a callback to the awaited task's list of callbacks indicating it
211-
should resume the current task/coroutine when it (the awaited one)
212-
finishes.
213-
In other words, when that awaited task finishes, the original task is
214-
added back to the event loops queue.
209+
In the process of relinquishing control a few important things happen.
210+
We'll use the following code example to illustrate::
211+
212+
async def plant_a_tree():
213+
dig_the_hole_task = asyncio.create_task(dig_the_hole())
214+
await dig_the_hole_task
215+
216+
# Other instructions associated with planting a tree.
217+
...
218+
219+
In this example, imagine the event loop has passed control to the start of the
220+
coroutine ``plant_a_tree()``.
221+
As seen above, that coroutine creates a task, then awaits it.
222+
The ``await dig_the_hole_task`` instruction adds a callback, which will resume
223+
``plant_a_tree()``, to the ``dig_the_hole_task`` object's list of callbacks.
224+
Eventually, the event loop will pass control to the ``dig_the_hole_task``
225+
and the task will finish whatever it needs to do.
226+
Once the task finishes, it will add the various callbacks to the event loop,
227+
in this case, a call to resume ``plant_a_tree()``.
228+
229+
Generally speaking, when the awaited task finishes (``dig_the_hole_task``),
230+
the original task or coroutine (``plant_a_tree()``) is added back to the event
231+
loops queue to be resumed.
215232

216233
This is a basic, yet reliable mental model.
217234
In practice, it's slightly more complex, but not by much.

0 commit comments

Comments
 (0)