[Python-checkins] gh-86128: Add warning to ThreadPoolExecutor docs about atexit behaviour (GH-94008)

[miss-islington]

https://github.com/python/cpython/commit/b50f58ecb4a15a004c83074276f079c982574732
commit: b50f58ecb4a15a004c83074276f079c982574732
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2022-07-28T15:46:45-07:00
summary:

gh-86128: Add warning to ThreadPoolExecutor docs about atexit behaviour (GH-94008)

(cherry picked from commit 7df2f4d78714707cfb30d83ca99ce84ef9934892)

Co-authored-by: [object Object] <lucas.wiman at gmail.com>

files:
A Misc/NEWS.d/next/Documentation/2022-06-19-18-18-22.gh-issue-86128.39DDTD.rst
M Doc/library/concurrent.futures.rst

diff --git a/Doc/library/concurrent.futures.rst b/Doc/library/concurrent.futures.rst
index 8efbf0a3d5955..db5971e4d60fc 100644
--- a/Doc/library/concurrent.futures.rst
+++ b/Doc/library/concurrent.futures.rst
@@ -149,6 +149,13 @@ And::
    An :class:`Executor` subclass that uses a pool of at most *max_workers*
    threads to execute calls asynchronously.
 
+   All threads enqueued to ``ThreadPoolExecutor`` will be joined before the
+   interpreter can exit. Note that the exit handler which does this is
+   executed *before* any exit handlers added using `atexit`. This means
+   exceptions in the main thread must be caught and handled in order to
+   signal threads to exit gracefully. For this reason, it is recommended
+   that ``ThreadPoolExecutor`` not be used for long-running tasks.
+
    *initializer* is an optional callable that is called at the start of
    each worker thread; *initargs* is a tuple of arguments passed to the
    initializer.  Should *initializer* raise an exception, all currently
diff --git a/Misc/NEWS.d/next/Documentation/2022-06-19-18-18-22.gh-issue-86128.39DDTD.rst b/Misc/NEWS.d/next/Documentation/2022-06-19-18-18-22.gh-issue-86128.39DDTD.rst
new file mode 100644
index 0000000000000..bab006856deea
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2022-06-19-18-18-22.gh-issue-86128.39DDTD.rst
@@ -0,0 +1 @@
+Document a limitation in ThreadPoolExecutor where its exit handler is executed before any handlers in atexit.