@@ -98,9 +98,11 @@ Concurrency and multithreading
98
98
99
99
An event loop runs in a thread (typically the main thread) and executes
100
100
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.
104
106
105
107
To schedule a callback from a different thread, the
106
108
:meth: `loop.call_soon_threadsafe ` method should be used. Example::
@@ -123,9 +125,9 @@ To schedule a coroutine object from a different thread, the
123
125
future = asyncio.run_coroutine_threadsafe(coro_func(), loop)
124
126
result = future.result(timeout) # Wait for the result with a timeout
125
127
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 .
129
131
130
132
.. seealso ::
131
133
@@ -183,9 +185,10 @@ Detect coroutine objects never scheduled
183
185
----------------------------------------
184
186
185
187
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 >`
189
192
to :ref: `log a warning <asyncio-logger >` to detect it.
190
193
191
194
Example with the bug::
@@ -204,8 +207,9 @@ Output in debug mode::
204
207
File "test.py", line 7, in <module>
205
208
test()
206
209
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.
209
213
210
214
.. seealso ::
211
215
@@ -280,14 +284,9 @@ coroutine in another coroutine and use classic try/except::
280
284
loop.run_forever()
281
285
loop.close()
282
286
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::
285
288
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())
291
290
292
291
.. seealso ::
293
292
0 commit comments