New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
av_undef's POD is confusing #12880
Comments
From @bulk88Created by @bulk88av_undef's POD last got worked on in Undefines the array. Frees the memory used by the av to store its list of =cut av_clear's POD says "Perl equivalent: C<@myarray = ();>." Wouldn't Another problem is, " Frees the memory used by the av to store its list Maybe " If any destructors are triggered as a result, the av itself may Perl Info
|
From @iabynOn Mon, Mar 25, 2013 at 08:56:15AM -0700, bulk88 wrote:
av_clear(): @array = ()A;
That's not really right. It's not that there's a circular chain of sub A::DESTROY{ $ra = 0 } How about: Warning: it is possible that the actions of a destructor called -- |
The RT System itself - Status changed from 'new' to 'open' |
From @ikegamiOn Mon, Mar 25, 2013 at 8:04 PM, Dave Mitchell <davem@iabyn.com> wrote:
"...unless you increment its reference count first"? |
From @bulk88On Mon Mar 25 17:04:59 2013, davem 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)? -- |
From @bulk88On Fri Feb 28 22:36:53 2014, bulk88 wrote:
Bump. -- |
From @jkeenanOn Mon Mar 25 08:56:15 2013, bulk88 wrote:
Could someone familiar with the Perl API comment on this documentation-related ticket dating from March 2013? Thank you very much. -- |
From @iabynOn Fri, Feb 28, 2014 at 10:36:53PM -0800, bulk88 via RT wrote:
I'd argue that having the warnings for at least some functions is better How about the following diff, which attempts to rationalise the four Inline Patchdiff --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. |
From @rurban
av_clear is equivalent to @a = ();
So on the script level they are very similar. av_undef changes the type.
No.
No, the current doc is better. To the differences: av_undef will clear the whole AvALLOC buffer. |
From @iabynOn Tue, Oct 06, 2015 at 11:52:22AM +0100, Dave Mitchell wrote:
I've now pushed that as a4395eb. -- |
@iabyn - Status changed from 'open' to 'resolved' |
Migrated from rt.perl.org#117341 (status was 'resolved')
Searchable as RT117341$
The text was updated successfully, but these errors were encountered: