diff options
Diffstat (limited to 'systems/texlive/tlnet/tlpkg/tlperl/lib/CORE/av.h')
-rw-r--r-- | systems/texlive/tlnet/tlpkg/tlperl/lib/CORE/av.h | 119 |
1 files changed, 112 insertions, 7 deletions
diff --git a/systems/texlive/tlnet/tlpkg/tlperl/lib/CORE/av.h b/systems/texlive/tlnet/tlpkg/tlperl/lib/CORE/av.h index 41cb6fefd8..6e0b24d7b3 100644 --- a/systems/texlive/tlnet/tlpkg/tlperl/lib/CORE/av.h +++ b/systems/texlive/tlnet/tlpkg/tlperl/lib/CORE/av.h @@ -18,16 +18,27 @@ 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 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. Examples include "@_" (unless tied), the + * scratchpad list, and the backrefs list on an object or stash. + * * 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.) * @@ -97,16 +108,110 @@ If all you need is to look up an array element, then prefer C<av_fetch>. #define NEGATIVE_INDICES_VAR "NEGATIVE_INDICES" /* + +Note that there are both real and fake AVs; see the beginning of this file and +'av.c' + =for apidoc newAV +=for apidoc_item newAV_alloc_x +=for apidoc_item newAV_alloc_xz + +These all create a new AV, setting the reference count to 1. If you also know +the initial elements of the array with, see L</C<av_make>>. + +As background, an array consists of three things: + +=over + +=item 1. + +A data structure containing information about the array as a whole, such as its +size and reference count. + +=item 2. + +A C language array of pointers to the individual elements. These are treated +as pointers to SVs, so all must be castable to SV*. + +=item 3. + +The individual elements themselves. These could be, for instance, SVs and/or +AVs and/or HVs, etc. + +=back + +An empty array need only have the first data structure, and all these functions +create that. They differ in what else they do, as follows: + +=over + +=item C<newAV> form + +=for comment +'form' above and below is because otherwise have two =items with the same name, +can't link to them. + +This does nothing beyond creating the whole-array data structure. +The Perl equivalent is approximately S<C<my @array;>> -Creates a new AV. The reference count is set to 1. +This is useful when the minimum size of the array could be zero (perhaps there +are likely code paths that will entirely skip using it). -Perl equivalent: C<my @array;>. +If the array does get used, the pointers data structure will need to be +allocated at that time. This will end up being done by L</av_extend>>, +either explicitly: + + av_extend(av, len); + +or implicitly when the first element is stored: + + (void)av_store(av, 0, sv); + +Unused array elements are typically initialized by C<av_extend>. + +=item C<newAV_alloc_x> form + +This effectively does a C<newAV> followed by also allocating (uninitialized) +space for the pointers array. This is used when you know ahead of time the +likely minimum size of the array. It is more efficient to do this than doing a +plain C<newAV> followed by an C<av_extend>. + +Of course the array can be extended later should it become necessary. + +C<size> must be at least 1. + +=item C<newAV_alloc_xz> form + +This is C<newAV_alloc_x>, but initializes each pointer in it to NULL. This +gives added safety to guard against them being read before being set. + +C<size> must be at least 1. + +=back + +The following examples all result in an array that can fit four elements +(indexes 0 .. 3): + + AV *av = newAV(); + av_extend(av, 3); + + AV *av = newAV_alloc_x(4); + + AV *av = newAV_alloc_xz(4); + +In contrast, the following examples allocate an array that is only guaranteed +to fit one element without extending: + + AV *av = newAV_alloc_x(1); + AV *av = newAV_alloc_xz(1); =cut + */ #define newAV() MUTABLE_AV(newSV_type(SVt_PVAV)) +#define newAV_alloc_x(size) av_new_alloc(size,0) +#define newAV_alloc_xz(size) av_new_alloc(size,1) /* * ex: set ts=8 sts=4 sw=4 et: |