[3.11] gh-109955 : Update state transition comments for asyncio.Task (GH-109910) (#109993)

miss-islington · kristjanvalur · AA-Turner · web-flow · commit 4b97c724e071 · 2023-09-29T15:25:34.000+02:00
gh-109955 : Update state transition comments for asyncio.Task (GH-109910) (cherry picked from commit 45cf5b0) Co-authored-by: Kristján Valur Jónsson <sweskman@gmail.com> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
diff --git a/Lib/asyncio/tasks.py b/Lib/asyncio/tasks.py
@@ -81,15 +81,25 @@ class Task(futures._PyFuture):  # Inherit Python Task implementation
     """A coroutine wrapped in a Future."""
 
     # An important invariant maintained while a Task not done:
+    # _fut_waiter is either None or a Future.  The Future
+    # can be either done() or not done().
+    # The task can be in any of 3 states:
     #
-    # - Either _fut_waiter is None, and _step() is scheduled;
-    # - or _fut_waiter is some Future, and _step() is *not* scheduled.
+    # - 1: _fut_waiter is not None and not _fut_waiter.done():
+    #      __step() is *not* scheduled and the Task is waiting for _fut_waiter.
+    # - 2: (_fut_waiter is None or _fut_waiter.done()) and __step() is scheduled:
+    #       the Task is waiting for __step() to be executed.
+    # - 3:  _fut_waiter is None and __step() is *not* scheduled:
+    #       the Task is currently executing (in __step()).
     #
-    # The only transition from the latter to the former is through
-    # _wakeup().  When _fut_waiter is not None, one of its callbacks
-    # must be _wakeup().
-
-    # If False, don't log a message if the task is destroyed whereas its
+    # * In state 1, one of the callbacks of __fut_waiter must be __wakeup().
+    # * The transition from 1 to 2 happens when _fut_waiter becomes done(),
+    #   as it schedules __wakeup() to be called (which calls __step() so
+    #   we way that __step() is scheduled).
+    # * It transitions from 2 to 3 when __step() is executed, and it clears
+    #   _fut_waiter to None.
+
+    # If False, don't log a message if the task is destroyed while its
     # status is still pending
     _log_destroy_pending = True
 
