diff options
author | Richard Leach <richardleach@users.noreply.github.com> | 2021-08-19 23:00:01 +0100 |
---|---|---|
committer | Karl Williamson <khw@cpan.org> | 2021-08-27 07:11:48 -0600 |
commit | 4762e1f88cc9ef2d1223b060db61846ba24eff35 (patch) | |
tree | a880746c67391118a6202db02ca44d9aab6291d1 /av.h | |
parent | 9d1dc8e3bf4c4286d3d098f35f83be5d6c34478a (diff) | |
download | perl-4762e1f88cc9ef2d1223b060db61846ba24eff35.tar.gz |
av.h: additional comments regarding real/fake AVs
Diffstat (limited to 'av.h')
-rw-r--r-- | av.h | 20 |
1 files changed, 15 insertions, 5 deletions
@@ -18,16 +18,26 @@ struct xpvav { /* SV* xav_arylen; */ -/* SVpav_REAL is set for all AVs whose xav_array contents are refcounted. - * Some things like "@_" and the scratchpad list do not set this, to - * indicate that they are cheating (for efficiency) by not refcounting - * the AV's contents. - * +/* SVpav_REAL is set for all AVs whose xav_array contents are refcounted + * and initialized such that any element can be retrieved as a SV*. + * Such AVs may be referred to as "real" AVs. Examples include regular + * perl arrays, tiedarrays (since v5.16), and padlist AVs. + * + * Some things like "@_" (unless tied) and the scratchpad list do not set + * SVpav_REAL, to indicate that they are cheating (for efficiency) by not + * refcounting the AV's contents or ensuring that all elements are safe for + * arbitrary access. This type of AV may be referred to as "fake" AVs. + * * SVpav_REIFY is only meaningful on such "fake" AVs (i.e. where SVpav_REAL * is not set). It indicates that the fake AV is capable of becoming * real if the array needs to be modified in some way. Functions that * modify fake AVs check both flags to call av_reify() as appropriate. * + * av_reify() transforms a fake AV into a real one through two actions. + * Allocated but unpopulated elements are initialized to make them safe for + * arbitrary retrieval and the reference counts of populated elements are + * incremented. + * * Note that the Perl stack has neither flag set. (Thus, * items that go on the stack are never refcounted.) * |