bpo-37261: Document sys.unraisablehook corner cases (GH-14059)
Document reference cycle and resurrected objects issues in
sys.unraisablehook() and threading.excepthook() documentation.
Fix test.support.catch_unraisable_exception(): __exit__() no longer
ignores unraisable exceptions.
Fix test_io test_writer_close_error_on_close(): use a second
catch_unraisable_exception() to catch the BufferedWriter unraisable
exception.
(cherry picked from commit 212646cae6b7c4ddc8d98c8b9b6d39a5f259e864)
Co-authored-by: Victor Stinner <vstinner@redhat.com>
diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index 2907b65..9ffd5cd 100644
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -58,6 +58,14 @@
:func:`threading.excepthook` can be overridden to control how uncaught
exceptions raised by :func:`Thread.run` are handled.
+ Storing *exc_value* using a custom hook can create a reference cycle. It
+ should be cleared explicitly to break the reference cycle when the
+ exception is no longer needed.
+
+ Storing *object* using a custom hook can resurrect it if it is set to an
+ object which is being finalized. Avoid storing *object* after the custom
+ hook completes to avoid resurrecting objects.
+
.. seealso::
:func:`sys.excepthook` handles uncaught exceptions.