Skip to content

Commit

Permalink
pythongh-97696: Improve and fix documentation
Browse files Browse the repository at this point in the history
- Document `eager_start` argument to Task constructor
- Document usage of `create_eager_task_factory`
- Fix docs nit from https://github.com/python/cpython/pull/104140/files#r1186714354
  • Loading branch information
itamaro committed May 7, 2023
1 parent f94d22f commit ac1ee82
Show file tree
Hide file tree
Showing 2 changed files with 20 additions and 2 deletions.
19 changes: 18 additions & 1 deletion Doc/library/asyncio-task.rst
Original file line number Diff line number Diff line change
Expand Up @@ -560,6 +560,13 @@ Eager Task Factory
using the provided *custom_task_constructor* when creating a new task instead
of the default :class:`Task`.

*custom_task_constructor* must be a *callable* with the signature matching
``(coro, *, loop=None, name=None, context=None, eager_start=False)``.
The callable must return a :class:`asyncio.Task`-compatible object.

This function returns a *callable* intended to be used as a task factory of an
event loop via :meth:`loop.set_task_factory(factory) <loop.set_task_factory>`).

.. versionadded:: 3.12


Expand Down Expand Up @@ -1014,7 +1021,7 @@ Introspection
Task Object
===========

.. class:: Task(coro, *, loop=None, name=None, context=None)
.. class:: Task(coro, *, loop=None, name=None, context=None, eager_start=False)

A :class:`Future-like <Future>` object that runs a Python
:ref:`coroutine <coroutine>`. Not thread-safe.
Expand Down Expand Up @@ -1054,6 +1061,13 @@ Task Object
If no *context* is provided, the Task copies the current context
and later runs its coroutine in the copied context.

An optional keyword-only *eager_start* argument allows eagerly starting
the execution of the :class:`asyncio.Task` at task creation time.
If set to ``True`` and the event loop is running, the task will start
executing the coroutine immediately, until the first time the coroutine
blocks. If the coroutine returns or raises without blocking, the task
will be finished eagerly and will skip scheduling to the event loop.

.. versionchanged:: 3.7
Added support for the :mod:`contextvars` module.

Expand All @@ -1067,6 +1081,9 @@ Task Object
.. versionchanged:: 3.11
Added the *context* parameter.

.. versionchanged:: 3.12
Added the *eager_start* parameter.

.. method:: done()

Return ``True`` if the Task is *done*.
Expand Down
Original file line number Diff line number Diff line change
@@ -1 +1,2 @@
Optimize :class:`asyncio.TaskGroup` when using :func:`asyncio.eager_task_factory`. Skip scheduling done callbacks when all tasks finish without blocking.
Optimize :class:`asyncio.TaskGroup` when using :func:`asyncio.eager_task_factory`.
Skip scheduling a done callback if a TaskGroup task completes eagerly.

0 comments on commit ac1ee82

Please sign in to comment.