Added info about the right way to leave the body of a trashcan-protected

destructor early.

diff --git a/Include/object.h b/Include/object.h
index 4987e12946812ea93c7d387ea266eb54676b1857..19460fe381c646f64cf40089aafacfe729831efa 100644 (file)
--- a/Include/object.h
+++ b/Include/object.h
@@ -706,6 +706,11 @@ mytype_dealloc(mytype *p)
        Py_TRASHCAN_SAFE_END(p)
 }
 
+CAUTION:  Never return from the middle of the body!  If the body needs to
+"get out early", put a label immediately before the Py_TRASHCAN_SAFE_END
+call, and goto it.  Else the call-depth counter (see below) will stay
+above 0 forever, and the trashcan will never get emptied.
+
 How it works:  The BEGIN macro increments a call-depth counter.  So long
 as this counter is small, the body of the deallocator is run directly without
 further ado.  But if the counter gets large, it instead adds p to a list of