Skip to content

Commit 1abba45

Browse files
willingc1st1
authored andcommitted
Polish doc as part of asyncio doc improvement (GH-9185)
1 parent 4ae8ece commit 1abba45

File tree

1 file changed

+17
-18
lines changed

1 file changed

+17
-18
lines changed

Doc/library/asyncio-dev.rst

Lines changed: 17 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -98,9 +98,11 @@ Concurrency and multithreading
9898

9999
An event loop runs in a thread (typically the main thread) and executes
100100
all callbacks and tasks in its thread. While a task is running in the
101-
event loop, no other task is running in the same thread. When a task
102-
executes an ``await`` expression, the task gets suspended and the
103-
event loop executes the next task.
101+
event loop, no other tasks may run in the same thread. When a task
102+
executes an ``await`` expression, the running task gets suspended, and the
103+
event loop executes the next task. Prior to suspending the task, the awaiting
104+
chain is checked, and if the chain ends with a future, the running task is
105+
not suspended.
104106

105107
To schedule a callback from a different thread, the
106108
:meth:`loop.call_soon_threadsafe` method should be used. Example::
@@ -123,9 +125,9 @@ To schedule a coroutine object from a different thread, the
123125
future = asyncio.run_coroutine_threadsafe(coro_func(), loop)
124126
result = future.result(timeout) # Wait for the result with a timeout
125127

126-
The :meth:`loop.run_in_executor` method can be used with a thread pool
127-
executor to execute a callback in different thread to not block the thread of
128-
the event loop.
128+
The :meth:`loop.run_in_executor` method can be used with a
129+
:class:`concurrent.futures.ThreadPoolExecutor` to execute a callback in
130+
different thread so as not to block the event loop's main thread.
129131

130132
.. seealso::
131133

@@ -183,9 +185,10 @@ Detect coroutine objects never scheduled
183185
----------------------------------------
184186

185187
When a coroutine function is called and its result is not passed to
186-
:func:`ensure_future` or to the :meth:`loop.create_task` method,
187-
the execution of the coroutine object will never be scheduled which is
188-
probably a bug. :ref:`Enable the debug mode of asyncio <asyncio-debug-mode>`
188+
:meth:`asyncio.create_task` the execution of the coroutine object will
189+
never be scheduled which is probably a bug. Using ``asyncio.create_task`` is
190+
preferred to the low level :func:`ensure_future` and :meth:`loop.create_task`
191+
methods. :ref:`Enable the debug mode of asyncio <asyncio-debug-mode>`
189192
to :ref:`log a warning <asyncio-logger>` to detect it.
190193

191194
Example with the bug::
@@ -204,8 +207,9 @@ Output in debug mode::
204207
File "test.py", line 7, in <module>
205208
test()
206209

207-
The fix is to call the :func:`ensure_future` function or the
208-
:meth:`loop.create_task` method with the coroutine object.
210+
The fix is to call the :meth:`asyncio.create_task` function. Using
211+
``asyncio.create_task`` is preferred to the low level :func:`ensure_future` and
212+
:meth:`loop.create_task` methods.
209213

210214
.. seealso::
211215

@@ -280,14 +284,9 @@ coroutine in another coroutine and use classic try/except::
280284
loop.run_forever()
281285
loop.close()
282286

283-
Another option is to use the :meth:`loop.run_until_complete`
284-
function::
287+
Another option is to use the :meth:`asyncio.run` function::
285288

286-
task = asyncio.ensure_future(bug())
287-
try:
288-
loop.run_until_complete(task)
289-
except Exception:
290-
print("exception consumed")
289+
asyncio.run(bug())
291290

292291
.. seealso::
293292

0 commit comments

Comments
 (0)