From 1abba455d1e703b7050c0d183e40c6a9d45798c5 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Wed, 12 Sep 2018 22:40:37 -0700 Subject: [PATCH] Polish doc as part of asyncio doc improvement (GH-9185) --- Doc/library/asyncio-dev.rst | 35 +++++++++++++++++------------------ 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst index cb574c308ad..e4986ba5eb2 100644 --- a/Doc/library/asyncio-dev.rst +++ b/Doc/library/asyncio-dev.rst @@ -98,9 +98,11 @@ Concurrency and multithreading 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 -event loop, no other task is running in the same thread. When a task -executes an ``await`` expression, the task gets suspended and the -event loop executes the next task. +event loop, no other tasks may run in the same thread. When a task +executes an ``await`` expression, the running task gets suspended, and the +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 :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) 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 -executor to execute a callback in different thread to not block the thread of -the event loop. +The :meth:`loop.run_in_executor` method can be used with a +:class:`concurrent.futures.ThreadPoolExecutor` to execute a callback in +different thread so as not to block the event loop's main thread. .. seealso:: @@ -183,9 +185,10 @@ Detect coroutine objects never scheduled ---------------------------------------- When a coroutine function is called and its result is not passed to -:func:`ensure_future` or to the :meth:`loop.create_task` method, -the execution of the coroutine object will never be scheduled which is -probably a bug. :ref:`Enable the debug mode of asyncio ` +:meth:`asyncio.create_task` the execution of the coroutine object will +never be scheduled which is probably a bug. Using ``asyncio.create_task`` is +preferred to the low level :func:`ensure_future` and :meth:`loop.create_task` +methods. :ref:`Enable the debug mode of asyncio ` to :ref:`log a warning ` to detect it. Example with the bug:: @@ -204,8 +207,9 @@ Output in debug mode:: File "test.py", line 7, in test() -The fix is to call the :func:`ensure_future` function or the -:meth:`loop.create_task` method with the coroutine object. +The fix is to call the :meth:`asyncio.create_task` function. Using +``asyncio.create_task`` is preferred to the low level :func:`ensure_future` and +:meth:`loop.create_task` methods. .. seealso:: @@ -280,14 +284,9 @@ coroutine in another coroutine and use classic try/except:: loop.run_forever() loop.close() -Another option is to use the :meth:`loop.run_until_complete` -function:: +Another option is to use the :meth:`asyncio.run` function:: - task = asyncio.ensure_future(bug()) - try: - loop.run_until_complete(task) - except Exception: - print("exception consumed") + asyncio.run(bug()) .. seealso::