traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Polish doc as part of asyncio doc improvement (GH-9185)

This commit is contained in:
Carol Willing 2018-09-12 22:40:37 -07:00 committed by Yury Selivanov
parent 4ae8ece5cd
commit 1abba455d1
1 changed files with 17 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
Doc/library/asyncio-dev.rst
View File

@ -98,9 +98,11 @@ Concurrency and multithreading
An event loop runs in a thread (typically the main thread) and executes An event loop runs in a thread (typically the main thread) and executes
all callbacks and tasks in its thread. While a task is running in the all callbacks and tasks in its thread. While a task is running in the
event loop, no other task is running in the same thread. When a task event loop, no other tasks may run in the same thread. When a task
executes an ``await`` expression, the task gets suspended and the executes an ``await`` expression, the running task gets suspended, and the
event loop executes the next task. event loop executes the next task. Prior to suspending the task, the awaiting
chain is checked, and if the chain ends with a future, the running task is
not suspended.
To schedule a callback from a different thread, the To schedule a callback from a different thread, the
:meth:`loop.call_soon_threadsafe` method should be used. Example:: :meth:`loop.call_soon_threadsafe` method should be used. Example::
@ -123,9 +125,9 @@ To schedule a coroutine object from a different thread, the
future = asyncio.run_coroutine_threadsafe(coro_func(), loop) future = asyncio.run_coroutine_threadsafe(coro_func(), loop)
result = future.result(timeout) # Wait for the result with a timeout result = future.result(timeout) # Wait for the result with a timeout
The :meth:`loop.run_in_executor` method can be used with a thread pool The :meth:`loop.run_in_executor` method can be used with a
executor to execute a callback in different thread to not block the thread of :class:`concurrent.futures.ThreadPoolExecutor` to execute a callback in
the event loop. different thread so as not to block the event loop's main thread.
.. seealso:: .. seealso::
@ -183,9 +185,10 @@ Detect coroutine objects never scheduled
---------------------------------------- ----------------------------------------
When a coroutine function is called and its result is not passed to When a coroutine function is called and its result is not passed to
:func:`ensure_future` or to the :meth:`loop.create_task` method, :meth:`asyncio.create_task` the execution of the coroutine object will
the execution of the coroutine object will never be scheduled which is never be scheduled which is probably a bug. Using ``asyncio.create_task`` is
probably a bug. :ref:`Enable the debug mode of asyncio <asyncio-debug-mode>` preferred to the low level :func:`ensure_future` and :meth:`loop.create_task`
methods. :ref:`Enable the debug mode of asyncio <asyncio-debug-mode>`
to :ref:`log a warning <asyncio-logger>` to detect it. to :ref:`log a warning <asyncio-logger>` to detect it.
Example with the bug:: Example with the bug::
@ -204,8 +207,9 @@ Output in debug mode::
File "test.py", line 7, in <module> File "test.py", line 7, in <module>
test() test()
The fix is to call the :func:`ensure_future` function or the The fix is to call the :meth:`asyncio.create_task` function. Using
:meth:`loop.create_task` method with the coroutine object. ``asyncio.create_task`` is preferred to the low level :func:`ensure_future` and
:meth:`loop.create_task` methods.
.. seealso:: .. seealso::
@ -280,14 +284,9 @@ coroutine in another coroutine and use classic try/except::
loop.run_forever() loop.run_forever()
loop.close() loop.close()
Another option is to use the :meth:`loop.run_until_complete` Another option is to use the :meth:`asyncio.run` function::
function::
task = asyncio.ensure_future(bug()) asyncio.run(bug())
try:
loop.run_until_complete(task)
except Exception:
print("exception consumed")
.. seealso:: .. seealso::