From 5d20a535e7147410037b506027fa7cc28b7ac1b8 Mon Sep 17 00:00:00 2001 From: Rohan McGovern Date: Wed, 2 Jan 2019 18:40:57 +1000 Subject: [PATCH] doc: expand on shutdown and thread leaks Fixes #94 --- docs/api-reference.rst | 7 +++++++ docs/user-guide.rst | 13 +++++++++++-- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/api-reference.rst b/docs/api-reference.rst index f092faab..5e7c113a 100644 --- a/docs/api-reference.rst +++ b/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: diff --git a/docs/user-guide.rst b/docs/user-guide.rst index 4766a57a..12693218 100644 --- a/docs/user-guide.rst +++ b/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`.