@@ -204,14 +204,31 @@ different ways::
204204In a crucial way, the behavior of ``await `` depends on the type of object
205205being 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
208208the 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
216233This is a basic, yet reliable mental model.
217234In practice, it's slightly more complex, but not by much.
0 commit comments