Re: [perl #117341] av_undef's POD is confusing

On Fri, Feb 28, 2014 at 10:36:53PM -0800, bulk88 via RT wrote:
> Looking at this ticket again. I think the warning shouldn't be there at
> all about av_undef and destructors and self referential destruction.
> Wouldn't that then apply to av_store, sv_clear and sv_setsv(sv,
> &PL_sv_undef) too? and every SV manipulation function that can change a
> reference or manipulate an aggregate (HV/AV/GV)?

I'd argue that having the warnings for at least some functions is better
than no warnings at all.

How about the following diff, which attempts to rationalise the four
[ah]v_(clear|undef) pod entries:

diff --git a/av.c b/av.c
index 2c4740b..9a5644a 100644
--- a/av.c
+++ b/av.c
@@ -436,11 +436,15 @@ Perl_av_make(pTHX_ SSize_t size, SV **strp)
 /*
 =for apidoc av_clear
 
-Clears an array, making it empty.  Does not free the memory C<av> uses to
-store its list of scalars.  If any destructors are triggered as a result,
-C<av> itself may be freed when this function returns.
+Frees the all the elements of an array, leaving it empty.
+The XS equivalent of C<@array = ()>.  See also L</av_undef>.
 
-Perl equivalent: C<@myarray = ();>.
+Note that it is possible that the actions of a destructor called directly
+or indirectly by freeing an element of the array could cause the reference
+count of the array itself to be reduced (e.g. by deleting an entry in the
+symbol table). So it is a possibility that the AV could have been freed
+(or even reallocated) on return from the call unless you hold a reference
+to it.
 
 =cut
 */
@@ -500,9 +504,13 @@ Perl_av_clear(pTHX_ AV *av)
 /*
 =for apidoc av_undef
 
-Undefines the array.  Frees the memory used by the av to store its list of
-scalars.  If any destructors are triggered as a result, C<av> itself may
-be freed.
+Undefines the array. The XS equivalent of C<undef(@array)>.
+
+As well as freeing all the elements of the array (like C<av_clear()>), this
+also frees the memory used by the av to store its list of scalars.
+
+See L</av_clear> for a note about the array possibly being invalid on
+return.
 
 =cut
 */
diff --git a/hv.c b/hv.c
index 253cad9..3bab3e2 100644
--- a/hv.c
+++ b/hv.c
@@ -1599,8 +1599,8 @@ Perl_hv_delayfree_ent(pTHX_ HV *hv, HE *entry)
 Frees the all the elements of a hash, leaving it empty.
 The XS equivalent of C<%hash = ()>.  See also L</hv_undef>.
 
-If any destructors are triggered as a result, the hv itself may
-be freed.
+See L</av_clear> for a note about the hash possibly being invalid on
+return.
 
 =cut
 */
@@ -1834,10 +1834,8 @@ Undefines the hash.  The XS equivalent of C<undef(%hash)>.
 As well as freeing all the elements of the hash (like C<hv_clear()>), this
 also frees any auxiliary data and storage associated with the hash.
 
-If any destructors are triggered as a result, the hv itself may
-be freed.
-
-See also L</hv_clear>.
+See L</av_clear> for a note about the hash possibly being invalid on
+return.
 
 =cut
 */




-- 
"Emacs isn't a bad OS once you get used to it.
It just lacks a decent editor."

• [perl #117341] av_undef's POD is confusing by bulk88 via RT
• Re: [perl #117341] av_undef's POD is confusing by Dave Mitchell
• Re: [perl #117341] av_undef's POD is confusing by Dave Mitchell