Merge #103

103: Fix (another) thread leak in ThrottleExecutor r=rohanpm a=rohanpm

The thread's main loop did "del executor" before waiting on the event,
but it could still hold a reference to the executor from 'to_submit'
or 'job'.

Fixes #93

Co-authored-by: Rohan McGovern <rohan@mcgovern.id.au>

docs/api-reference.rst

@@ -133,6 +133,13 @@ The poll function has the following semantics:
 - If the poll function returns an int or float, it is used as the delay
   in seconds until the next poll.
 
+.. warning::
+
+  The poll function should avoid holding a reference to the corresponding
+  :class:`~more_executors.poll.PollExecutor`. If it holds a reference to the
+  executor, invoking :meth:`~concurrent.futures.Executor.shutdown` becomes
+  mandatory in order to stop the polling thread.
+
 .. _cancel function:
 
 

docs/user-guide.rst

@@ -184,5 +184,14 @@ For example, this code is broken:
     with executor:
         do_something(executor)
 
-Shutting down executors is optional and is not necessary to (eventually)
-reclaim resources.
+Generally, shutting down executors is optional and is not necessary to
+(eventually) reclaim resources.
+
+However, where executors accept caller-provided code (such as the polling
+function to :class:`~more_executors.poll.PollExecutor` or the retry
+policy to :class:`~more_executors.retry.RetryExecutor`), it is easy to
+accidentally create a circular reference between the provided code and the
+executor. When this happens, it will no longer be possible for the garbage
+collector to clean up the executor's resources automatically and a thread
+leak may occur. If in doubt, call
+:meth:`~concurrent.futures.Executor.shutdown`.