prefer polymorphism on existing destructor over custom destructor method

1 files changed, 24 insertions, 0 deletions

diff --git a/Doc/Manual/Perl5.html b/Doc/Manual/Perl5.html
index 00284783f..db8c0e602 100644
--- a/Doc/Manual/Perl5.html
+++ b/Doc/Manual/Perl5.html
@@ -3231,6 +3231,30 @@ destroyed together. Destroying one without destroying the other will
 likely cause your program to segfault.
 </p>
 
+<p>
+Also note that due to the proxy implementation, the <tt>DESTROY()</tt>
+method on directors can be called for several reasons, many of which
+have little to do with the teardown of an object instance.  To help
+disambiguate this, a second argument is added to the <tt>DESTROY()</tt>
+call when a C++ director object is being released.  So, to avoid running
+your clean-up code when an object is not really going away, or after it
+has already been reclaimed, it is suggested that custom destructors in
+Perl subclasses looks something like:
+</p>
+
+<div class="targetlang">
+<pre>
+sub DESTROY {
+  my($self, $final) = @_;
+  if($final) {
+    # real teardown code
+  }
+  shift-&gt;SUPER::DESTROY(@_);
+}
+</pre>
+</div>
+
+
 <H3><a name="Perl5_nn51"></a>31.11.4 Exception unrolling</H3>