Document why is and is not a good way to fix the gc_inspection crasher.

1 files changed, 15 insertions, 0 deletions

diff --git a/Lib/test/crashers/gc_inspection.py b/Lib/test/crashers/gc_inspection.py
index b439ad9..10caa79 100644
--- a/Lib/test/crashers/gc_inspection.py
+++ b/Lib/test/crashers/gc_inspection.py
@@ -1,5 +1,20 @@
 """
 gc.get_referrers() can be used to see objects before they are fully built.
+
+Note that this is only an example.  There are many ways to crash Python
+by using gc.get_referrers(), as well as many extension modules (even
+when they are using perfectly documented patterns to build objects).
+
+Identifying and removing all places that expose to the GC a
+partially-built object is a long-term project.  A patch was proposed on
+SF specifically for this example but I consider fixing just this single
+example a bit pointless (#1517042).
+
+A fix would include a whole-scale code review, possibly with an API
+change to decouple object creation and GC registration, and according
+fixes to the documentation for extension module writers.  It's unlikely
+to happen, though.  So this is currently classified as
+"gc.get_referrers() is dangerous, use only for debugging".
 """
 
 import gc