CLN more comments to the references store in __init__

Author: tomMoral

Lib/concurrent/futures/process.py

@@ -270,24 +270,40 @@ class _ExecutorManagerThread(threading.Thread):
     """
 
     def __init__(self, executor):
+        # Store references to necessary internals of the executor.
+
+        # A _ThreadWakeup to allow waking up the queue_manager_thread from the
+        # main Thread and avoid deadlocks caused by permanently locked queues.
+        self.thread_wakeup = executor._executor_manager_thread_wakeup
 
+        # A weakref.ref to the ProcessPoolExecutor that owns this thread. Used
+        # to determine if the ProcessPoolExecutor has been garbage collected
+        # and that the manager can exit.
         # When the executor gets garbage collected, the weakref callback
         # will wake up the queue management thread so that it can terminate
         # if there is no pending work item.
-        self.thread_wakeup = executor._executor_manager_thread_wakeup
-
         def weakref_cb(_, thread_wakeup=self.thread_wakeup):
             mp.util.debug('Executor collected: triggering callback for'
                           ' QueueManager wakeup')
             thread_wakeup.wakeup()
 
         self.executor_reference = weakref.ref(executor, weakref_cb)
 
-        # Store references to necessary internals of the executor.
+        # A list of the ctx.Process instances used as workers.
         self.processes = executor._processes
+
+        # A ctx.Queue that will be filled with _CallItems derived from
+        # _WorkItems for processing by the process workers.
         self.call_queue = executor._call_queue
+
+        # A ctx.SimpleQueue of _ResultItems generated by the process workers.
         self.result_queue = executor._result_queue
+
+        # A queue.Queue of work ids e.g. Queue([5, 6, ...]).
         self.work_ids_queue = executor._work_ids
+
+        # A dict mapping work ids to _WorkItems e.g.
+        #     {5: <_WorkItem...>, 6: <_WorkItem...>, ...}
         self.pending_work_items = executor._pending_work_items
 
         # Set this thread to be daemonized

Misc/NEWS.d/next/Library/2020-02-28-12-59-30.bpo-39678.3idfxM.rst

@@ -1,3 +1,2 @@
 Refactor queue_manager in :class:`concurrent.futures.ProcessPoolExecutor` to
-make it easier to maintain.
-Contributed by <tommoral>.
+make it easier to maintain.