bpo-33649: First asyncio docs improvement pass #9142
Conversation
Rewritten/updated sections: * Event Loop APIs * Transports & Protocols * Streams * Exceptions * Policies * Queues * Subprocesses * Platforms
| .. class:: WindowsProactorEventLoopPolicy | ||
|
|
||
| An alternative event loop policy that uses the | ||
| :class:`ProactorEventLoop` event loop implementation. |
There was a problem hiding this comment.
Not sure I understand this comment :(
There was a problem hiding this comment.
No worries. The link didn't seem to land somewhere useful. We can revisit this in another PR..
There was a problem hiding this comment.
Interesting, the link works on my docs build and points to the ProactorEventLoop docs...
| and the event loop executes the next task. | ||
| 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 |
There was a problem hiding this comment.
no other tasks may run in the...
| 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 |
| @@ -122,7 +123,7 @@ 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:`AbstractEventLoop.run_in_executor` method can be used with a thread pool | |||
| The :meth:`loop.run_in_executor` method can be used with a thread pool | |||
There was a problem hiding this comment.
ThreadPoolExecutor to execute a callback in a different thread so as not to block the event loop's main thread.
| 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 |
There was a problem hiding this comment.
Technically the task can be suspended but if a future at the end of awaiting chain is ready no suspension is performed.
I described this behavior to many people. Stack Overflow also has questions like this.
Looks like we need to mention it here to avoid confusion.
| @@ -182,7 +183,7 @@ 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:`AbstractEventLoop.create_task` method, | |||
| :func:`ensure_future` or to the :meth:`loop.create_task` method, | |||
There was a problem hiding this comment.
Should we focus on asyncio.create_task() helper here?
| @@ -204,7 +205,7 @@ Output in debug mode:: | |||
| test() | |||
|
|
|||
| The fix is to call the :func:`ensure_future` function or the | |||
| :meth:`AbstractEventLoop.create_task` method with the coroutine object. | |||
| :meth:`loop.create_task` method with the coroutine object. | |||
There was a problem hiding this comment.
asyncio.create_task() again?
| @@ -279,7 +280,7 @@ coroutine in another coroutine and use classic try/except:: | |||
| loop.run_forever() | |||
| loop.close() | |||
|
|
|||
| Another option is to use the :meth:`AbstractEventLoop.run_until_complete` | |||
| Another option is to use the :meth:`loop.run_until_complete` | |||
There was a problem hiding this comment.
Should we promote asyncio.run() here?
|
Merged! |
This is a first PR in the series
Rewritten/updated sections:
https://bugs.python.org/issue33649