SV* newSVpvf(const char*, ...);
SV* newSVsv(SV*);
-C<STRLEN> is an integer type (Size_t, usually defined as size_t in
+C<STRLEN> is an integer type (C<Size_t>, usually defined as C<size_t> in
F<config.h>) guaranteed to be large enough to represent the size of
any string that perl can handle.
void sv_setpvn(SV*, const char*, STRLEN)
void sv_setpvf(SV*, const char*, ...);
void sv_vsetpvfn(SV*, const char*, STRLEN, va_list *,
- SV **, I32, bool *);
+ SV **, Size_t, bool *);
void sv_setsv(SV*, SV*);
Notice that you can choose to specify the length of the string to be
the format.
The C<sv_set*()> functions are not generic enough to operate on values
-that have "magic". See L<Magic Virtual Tables> later in this document.
+that have "magic". See L</Magic Virtual Tables> later in this document.
All SVs that contain strings should be terminated with a C<NUL> character.
If it is not C<NUL>-terminated there is a risk of
If you don't need the existing content of the SV, you can avoid some
copying with:
- sv_setpvn(sv, "", 0);
+ SvPVCLEAR(sv);
s = SvGROW(sv, needlen + 1);
/* something that modifies up to needlen bytes at s, but modifies
newlen bytes
to be interpreted as a string.
The C<sv_cat*()> functions are not generic enough to operate on values that
-have "magic". See L<Magic Virtual Tables> later in this document.
+have "magic". See L</Magic Virtual Tables> later in this document.
If you know the name of a scalar variable, you can get a pointer to its SV
by using the following:
So to repeat always use SvOK() to check whether an sv is defined.
Also you have to be careful when using C<&PL_sv_undef> as a value in
-AVs or HVs (see L<AVs, HVs and undefined values>).
+AVs or HVs (see L</AVs, HVs and undefined values>).
There are also the two values C<PL_sv_yes> and C<PL_sv_no>, which contain
boolean TRUE and FALSE values, respectively. Like C<PL_sv_undef>, their
first line and all will be well.
To free an SV that you've created, call C<SvREFCNT_dec(SV*)>. Normally this
-call is not necessary (see L<Reference Counts and Mortality>).
+call is not necessary (see L</Reference Counts and Mortality>).
=head2 Offsets
Notice here the LEN is 10. (It may differ on your platform.) Extend the
length of the string to one less than 10, and do a substitution:
- % ./perl -Ilib -MDevel::Peek -le '$a=""; $a.="123456789"; $a=~s/.//; Dump($a)'
- SV = PV(0x7ffa04008a70) at 0x7ffa04030390
- REFCNT = 1
- FLAGS = (POK,OOK,pPOK)
- OFFSET = 1
- PV = 0x7ffa03c05b61 ( "\1" . ) "23456789"\0
- CUR = 8
- LEN = 9
+ % ./perl -Ilib -MDevel::Peek -le '$a=""; $a.="123456789"; $a=~s/.//; \
+ Dump($a)'
+ SV = PV(0x7ffa04008a70) at 0x7ffa04030390
+ REFCNT = 1
+ FLAGS = (POK,OOK,pPOK)
+ OFFSET = 1
+ PV = 0x7ffa03c05b61 ( "\1" . ) "23456789"\0
+ CUR = 8
+ LEN = 9
Here the number of bytes chopped off (1) is shown next as the OFFSET. The
portion of the string between the "real" and the "fake" beginnings is
This returns NULL if the variable does not exist.
-See L<Understanding the Magic of Tied Hashes and Arrays> for more
+See L</Understanding the Magic of Tied Hashes and Arrays> for more
information on how to use the array access functions on tied arrays.
=head2 Working with HVs
of perl, and the return value may change per invocation, so the value
is only valid for the duration of a single perl process.
-See L<Understanding the Magic of Tied Hashes and Arrays> for more
+See L</Understanding the Magic of Tied Hashes and Arrays> for more
information on how to use the hash access functions on tied hashes.
+=for apidoc Amh|void|PERL_HASH|U32 hash|char *key|STRLEN klen
+
=head2 Hash API Extensions
Beginning with version 5.004, the following functions are also supported:
The most useful types that will be returned are:
- < SVt_PVAV Scalar
SVt_PVAV Array
SVt_PVHV Hash
SVt_PVCV Code
SVt_PVGV Glob (possibly a file handle)
+Any numerical value returned which is less than SVt_PVAV will be a scalar
+of some form.
+
See L<perlapi/svtype> for more details.
=head2 Blessed References and Class Objects
The C<sv> argument must be a reference value. The C<stash> argument
specifies which class the reference will belong to. See
-L<Stashes and Globs> for information on converting class names into stashes.
+L</Stashes and Globs> for information on converting class names into stashes.
/* Still under construction */
AVs, or HVs (xV for short in the following) start their life with a
reference count of 1. If the reference count of an xV ever drops to 0,
then it will be destroyed and its memory made available for reuse.
-
-This normally doesn't happen at the Perl level unless a variable is
-undef'ed or the last variable holding a reference to it is changed or
-overwritten. At the internal level, however, reference counts can be
-manipulated with the following macros:
+At the most basic internal level, reference counts can be manipulated
+with the following macros:
int SvREFCNT(SV* sv);
SV* SvREFCNT_inc(SV* sv);
void SvREFCNT_dec(SV* sv);
-However, there is one other function which manipulates the reference
-count of its argument. The C<newRV_inc> function, you will recall,
-creates a reference to the specified argument. As a side effect,
-it increments the argument's reference count. If this is not what
-you want, use C<newRV_noinc> instead.
-
-For example, imagine you want to return a reference from an XSUB function.
-Inside the XSUB routine, you create an SV which initially has a reference
-count of one. Then you call C<newRV_inc>, passing it the just-created SV.
-This returns the reference as a new SV, but the reference count of the
-SV you passed to C<newRV_inc> has been incremented to two. Now you
-return the reference from the XSUB routine and forget about the SV.
-But Perl hasn't! Whenever the returned reference is destroyed, the
-reference count of the original SV is decreased to one and nothing happens.
-The SV will hang around without any way to access it until Perl itself
-terminates. This is a memory leak.
-
-The correct procedure, then, is to use C<newRV_noinc> instead of
-C<newRV_inc>. Then, if and when the last reference is destroyed,
-the reference count of the SV will go to zero and it will be destroyed,
-stopping any memory leak.
+(There are also suffixed versions of the increment and decrement macros,
+for situations where the full generality of these basic macros can be
+exchanged for some performance.)
+
+However, the way a programmer should think about references is not so
+much in terms of the bare reference count, but in terms of I<ownership>
+of references. A reference to an xV can be owned by any of a variety
+of entities: another xV, the Perl interpreter, an XS data structure,
+a piece of running code, or a dynamic scope. An xV generally does not
+know what entities own the references to it; it only knows how many
+references there are, which is the reference count.
+
+To correctly maintain reference counts, it is essential to keep track
+of what references the XS code is manipulating. The programmer should
+always know where a reference has come from and who owns it, and be
+aware of any creation or destruction of references, and any transfers
+of ownership. Because ownership isn't represented explicitly in the xV
+data structures, only the reference count need be actually maintained
+by the code, and that means that this understanding of ownership is not
+actually evident in the code. For example, transferring ownership of a
+reference from one owner to another doesn't change the reference count
+at all, so may be achieved with no actual code. (The transferring code
+doesn't touch the referenced object, but does need to ensure that the
+former owner knows that it no longer owns the reference, and that the
+new owner knows that it now does.)
+
+An xV that is visible at the Perl level should not become unreferenced
+and thus be destroyed. Normally, an object will only become unreferenced
+when it is no longer visible, often by the same means that makes it
+invisible. For example, a Perl reference value (RV) owns a reference to
+its referent, so if the RV is overwritten that reference gets destroyed,
+and the no-longer-reachable referent may be destroyed as a result.
+
+Many functions have some kind of reference manipulation as
+part of their purpose. Sometimes this is documented in terms
+of ownership of references, and sometimes it is (less helpfully)
+documented in terms of changes to reference counts. For example, the
+L<newRV_inc()|perlapi/newRV_inc> function is documented to create a new RV
+(with reference count 1) and increment the reference count of the referent
+that was supplied by the caller. This is best understood as creating
+a new reference to the referent, which is owned by the created RV,
+and returning to the caller ownership of the sole reference to the RV.
+The L<newRV_noinc()|perlapi/newRV_noinc> function instead does not
+increment the reference count of the referent, but the RV nevertheless
+ends up owning a reference to the referent. It is therefore implied
+that the caller of C<newRV_noinc()> is relinquishing a reference to the
+referent, making this conceptually a more complicated operation even
+though it does less to the data structures.
+
+For example, imagine you want to return a reference from an XSUB
+function. Inside the XSUB routine, you create an SV which initially
+has just a single reference, owned by the XSUB routine. This reference
+needs to be disposed of before the routine is complete, otherwise it
+will leak, preventing the SV from ever being destroyed. So to create
+an RV referencing the SV, it is most convenient to pass the SV to
+C<newRV_noinc()>, which consumes that reference. Now the XSUB routine
+no longer owns a reference to the SV, but does own a reference to the RV,
+which in turn owns a reference to the SV. The ownership of the reference
+to the RV is then transferred by the process of returning the RV from
+the XSUB.
There are some convenience functions available that can help with the
destruction of xVs. These functions introduce the concept of "mortality".
-An xV that is mortal has had its reference count marked to be decremented,
-but not actually decremented, until "a short time later". Generally the
-term "short time later" means a single Perl statement, such as a call to
-an XSUB function. The actual determinant for when mortal xVs have their
-reference count decremented depends on two macros, SAVETMPS and FREETMPS.
-See L<perlcall> and L<perlxs> for more details on these macros.
-
-"Mortalization" then is at its simplest a deferred C<SvREFCNT_dec>.
-However, if you mortalize a variable twice, the reference count will
-later be decremented twice.
-
-"Mortal" SVs are mainly used for SVs that are placed on perl's stack.
-For example an SV which is created just to pass a number to a called sub
-is made mortal to have it cleaned up automatically when it's popped off
-the stack. Similarly, results returned by XSUBs (which are pushed on the
-stack) are often made mortal.
-
-To create a mortal variable, use the functions:
+Much documentation speaks of an xV itself being mortal, but this is
+misleading. It is really I<a reference to> an xV that is mortal, and it
+is possible for there to be more than one mortal reference to a single xV.
+For a reference to be mortal means that it is owned by the temps stack,
+one of perl's many internal stacks, which will destroy that reference
+"a short time later". Usually the "short time later" is the end of
+the current Perl statement. However, it gets more complicated around
+dynamic scopes: there can be multiple sets of mortal references hanging
+around at the same time, with different death dates. Internally, the
+actual determinant for when mortal xV references are destroyed depends
+on two macros, SAVETMPS and FREETMPS. See L<perlcall> and L<perlxs>
+and L</Temporaries Stack> below for more details on these macros.
+
+Mortal references are mainly used for xVs that are placed on perl's
+main stack. The stack is problematic for reference tracking, because it
+contains a lot of xV references, but doesn't own those references: they
+are not counted. Currently, there are many bugs resulting from xVs being
+destroyed while referenced by the stack, because the stack's uncounted
+references aren't enough to keep the xVs alive. So when putting an
+(uncounted) reference on the stack, it is vitally important to ensure that
+there will be a counted reference to the same xV that will last at least
+as long as the uncounted reference. But it's also important that that
+counted reference be cleaned up at an appropriate time, and not unduly
+prolong the xV's life. For there to be a mortal reference is often the
+best way to satisfy this requirement, especially if the xV was created
+especially to be put on the stack and would otherwise be unreferenced.
+
+To create a mortal reference, use the functions:
SV* sv_newmortal()
- SV* sv_2mortal(SV*)
SV* sv_mortalcopy(SV*)
+ SV* sv_2mortal(SV*)
-The first call creates a mortal SV (with no value), the second converts an existing
-SV to a mortal SV (and thus defers a call to C<SvREFCNT_dec>), and the
-third creates a mortal copy of an existing SV.
-Because C<sv_newmortal> gives the new SV no value, it must normally be given one
-via C<sv_setpv>, C<sv_setiv>, etc. :
+C<sv_newmortal()> creates an SV (with the undefined value) whose sole
+reference is mortal. C<sv_mortalcopy()> creates an xV whose value is a
+copy of a supplied xV and whose sole reference is mortal. C<sv_2mortal()>
+mortalises an existing xV reference: it transfers ownership of a reference
+from the caller to the temps stack. Because C<sv_newmortal> gives the new
+SV no value, it must normally be given one via C<sv_setpv>, C<sv_setiv>,
+etc. :
SV *tmp = sv_newmortal();
sv_setiv(tmp, an_integer);
SV *tmp = sv_2mortal(newSViv(an_integer));
-
-You should be careful about creating mortal variables. Strange things
-can happen if you make the same value mortal within multiple contexts,
-or if you make a variable mortal multiple
-times. Thinking of "Mortalization"
-as deferred C<SvREFCNT_dec> should help to minimize such problems.
-For example if you are passing an SV which you I<know> has a high enough REFCNT
-to survive its use on the stack you need not do any mortalization.
-If you are not sure then doing an C<SvREFCNT_inc> and C<sv_2mortal>, or
-making a C<sv_mortalcopy> is safer.
-
The mortal routines are not just for SVs; AVs and HVs can be
made mortal by passing their address (type-casted to C<SV*>) to the
C<sv_2mortal> or C<sv_mortalcopy> routines.
The sv_magic function uses C<how> to determine which, if any, predefined
"Magic Virtual Table" should be assigned to the C<mg_virtual> field.
-See the L<Magic Virtual Tables> section below. The C<how> argument is also
+See the L</Magic Virtual Tables> section below. The C<how> argument is also
stored in the C<mg_type> field. The value of
C<how> should be chosen from the set of macros
C<PERL_MAGIC_foo> found in F<perl.h>. Note that before
The C<obj> argument is stored in the C<mg_obj> field of the C<MAGIC>
structure. If it is not the same as the C<sv> argument, the reference
count of the C<obj> object is incremented. If it is the same, or if
-the C<how> argument is C<PERL_MAGIC_arylen>, or if it is a NULL pointer,
-then C<obj> is merely stored, without the reference count being incremented.
+the C<how> argument is C<PERL_MAGIC_arylen>, C<PERL_MAGIC_regdatum>,
+C<PERL_MAGIC_regdata>, or if it is a NULL pointer, then C<obj> is merely
+stored, without the reference count being incremented.
See also C<sv_magicext> in L<perlapi> for a more flexible way to add magic
to an SV.
The C<MGVTBL> has five (or sometimes eight) pointers to the following
routine types:
- int (*svt_get)(SV* sv, MAGIC* mg);
- int (*svt_set)(SV* sv, MAGIC* mg);
- U32 (*svt_len)(SV* sv, MAGIC* mg);
- int (*svt_clear)(SV* sv, MAGIC* mg);
- int (*svt_free)(SV* sv, MAGIC* mg);
+ int (*svt_get) (pTHX_ SV* sv, MAGIC* mg);
+ int (*svt_set) (pTHX_ SV* sv, MAGIC* mg);
+ U32 (*svt_len) (pTHX_ SV* sv, MAGIC* mg);
+ int (*svt_clear)(pTHX_ SV* sv, MAGIC* mg);
+ int (*svt_free) (pTHX_ SV* sv, MAGIC* mg);
- int (*svt_copy)(SV *sv, MAGIC* mg, SV *nsv,
+ int (*svt_copy) (pTHX_ SV *sv, MAGIC* mg, SV *nsv,
const char *name, I32 namlen);
- int (*svt_dup)(MAGIC *mg, CLONE_PARAMS *param);
- int (*svt_local)(SV *nsv, MAGIC *mg);
+ int (*svt_dup) (pTHX_ MAGIC *mg, CLONE_PARAMS *param);
+ int (*svt_local)(pTHX_ SV *nsv, MAGIC *mg);
This MGVTBL structure is set at compile-time in F<perl.h> and there are
v PERL_MAGIC_vec vtbl_vec vec() lvalue
w PERL_MAGIC_utf8 vtbl_utf8 Cached UTF-8 information
x PERL_MAGIC_substr vtbl_substr substr() lvalue
+ Y PERL_MAGIC_nonelem vtbl_nonelem Array element that does not
+ exist
y PERL_MAGIC_defelem vtbl_defelem Shadow "foreach" iterator
variable / smart parameter
vivification
~ PERL_MAGIC_ext (none) Available for use by
extensions
+
+=for apidoc Amnh||PERL_MAGIC_sv
+=for apidoc Amnh||PERL_MAGIC_arylen
+=for apidoc Amnh||PERL_MAGIC_rhash
+=for apidoc Amnh||PERL_MAGIC_debugvar
+=for apidoc Amnh||PERL_MAGIC_pos
+=for apidoc Amnh||PERL_MAGIC_symtab
+=for apidoc Amnh||PERL_MAGIC_backref
+=for apidoc Amnh||PERL_MAGIC_arylen_p
+=for apidoc Amnh||PERL_MAGIC_bm
+=for apidoc Amnh||PERL_MAGIC_overload_table
+=for apidoc Amnh||PERL_MAGIC_regdata
+=for apidoc Amnh||PERL_MAGIC_regdatum
+=for apidoc Amnh||PERL_MAGIC_env
+=for apidoc Amnh||PERL_MAGIC_envelem
+=for apidoc Amnh||PERL_MAGIC_fm
+=for apidoc Amnh||PERL_MAGIC_regex_global
+=for apidoc Amnh||PERL_MAGIC_hints
+=for apidoc Amnh||PERL_MAGIC_hintselem
+=for apidoc Amnh||PERL_MAGIC_isa
+=for apidoc Amnh||PERL_MAGIC_isaelem
+=for apidoc Amnh||PERL_MAGIC_nkeys
+=for apidoc Amnh||PERL_MAGIC_dbfile
+=for apidoc Amnh||PERL_MAGIC_dbline
+=for apidoc Amnh||PERL_MAGIC_shared
+=for apidoc Amnh||PERL_MAGIC_shared_scalar
+=for apidoc Amnh||PERL_MAGIC_collxfrm
+=for apidoc Amnh||PERL_MAGIC_tied
+=for apidoc Amnh||PERL_MAGIC_tiedelem
+=for apidoc Amnh||PERL_MAGIC_tiedscalar
+=for apidoc Amnh||PERL_MAGIC_qr
+=for apidoc Amnh||PERL_MAGIC_sig
+=for apidoc Amnh||PERL_MAGIC_sigelem
+=for apidoc Amnh||PERL_MAGIC_taint
+=for apidoc Amnh||PERL_MAGIC_uvar
+=for apidoc Amnh||PERL_MAGIC_uvar_elem
+=for apidoc Amnh||PERL_MAGIC_vstring
+=for apidoc Amnh||PERL_MAGIC_vec
+=for apidoc Amnh||PERL_MAGIC_utf8
+=for apidoc Amnh||PERL_MAGIC_substr
+=for apidoc Amnh||PERL_MAGIC_nonelem
+=for apidoc Amnh||PERL_MAGIC_defelem
+=for apidoc Amnh||PERL_MAGIC_lvref
+=for apidoc Amnh||PERL_MAGIC_checkcall
+=for apidoc Amnh||PERL_MAGIC_ext
+
=for mg_vtable.pl end
When an uppercase and lowercase letter both exist in the table, then the
the tie methods. Lastly it ties the two hashes together, and returns a
reference to the new tied hash. Note that the code below does NOT call the
TIEHASH method in the MyTie class -
-see L<Calling Perl Routines from within C Programs> for details on how
+see L</Calling Perl Routines from within C Programs> for details on how
to do this.
SV*
=item C<SAVEFREESV(SV *sv)>
-The refcount of C<sv> would be decremented at the end of
+The refcount of C<sv> will be decremented at the end of
I<pseudo-block>. This is similar to C<sv_2mortal> in that it is also a
mechanism for doing a delayed C<SvREFCNT_dec>. However, while C<sv_2mortal>
extends the lifetime of C<sv> until the beginning of the next statement,
=item C<SV* save_scalar(GV *gv)>
+=for apidoc save_scalar
+
Equivalent to Perl code C<local $gv>.
=item C<AV* save_ary(GV *gv)>
+=for apidoc save_ary
+
=item C<HV* save_hash(GV *gv)>
+=for apidoc save_hash
+
Similar to C<save_scalar>, but localize C<@gv> and C<%gv>.
=item C<void save_item(SV *item)>
-Duplicates the current value of C<SV>, on the exit from the current
-C<ENTER>/C<LEAVE> I<pseudo-block> will restore the value of C<SV>
+=for apidoc save_item
+
+Duplicates the current value of C<SV>. On the exit from the current
+C<ENTER>/C<LEAVE> I<pseudo-block> the value of C<SV> will be restored
using the stored value. It doesn't handle magic. Use C<save_scalar> if
magic is affected.
=item C<void save_list(SV **sarg, I32 maxsarg)>
+=for apidoc save_list
+
A variant of C<save_item> which takes multiple arguments via an array
C<sarg> of C<SV*> of length C<maxsarg>.
=item C<SV* save_svref(SV **sptr)>
+=for apidoc save_svref
+
Similar to C<save_scalar>, but will reinstate an C<SV *>.
=item C<void save_aptr(AV **aptr)>
=item C<void save_hptr(HV **hptr)>
+=for apidoc save_aptr
+=for apidoc save_hptr
+
Similar to C<save_svref>, but localize C<AV *> and C<HV *>.
=back
not constantly freed/created.
Each of the targets is created only once (but see
-L<Scratchpads and recursion> below), and when an opcode needs to put
+L</Scratchpads and recursion> below), and when an opcode needs to put
an integer, a double, or a string on stack, it just sets the
corresponding parts of its I<target> and puts the I<target> on stack.
creates two scopes: the first starts at the C<(> and has C<full == 1>,
the second starts at the C<{> and has C<full == 0>. Both end at the
-C<}>, so calls to C<start> and C<pre/post_end> will match. Anything
+C<}>, so calls to C<start> and C<pre>/C<post_end> will match. Anything
pushed onto the save stack by this hook will be popped just before the
scope ends (between the C<pre_> and C<post_end> hooks, in fact).
is also possible to use the C<BhkDISABLE> and C<BhkENABLE> macros to
temporarily switch entries on and off. You should also be aware that
generally speaking at least one scope will have opened before your
-extension is loaded, so you will see some C<pre/post_end> pairs that
+extension is loaded, so you will see some C<pre>/C<post_end> pairs that
didn't have a matching C<start>.
=head1 Examining internal data structures with the C<dump> functions
to use C<dVAR> in your coding to "declare the global variables"
when you are using them. dTHX does this for you automatically.
+=for apidoc Amnh||dVAR
+
To see whether you have non-const data you can use a BSD (or GNU)
compatible C<nm>:
or 'd' for B<d>eclaration, so we have C<pTHX>, C<aTHX> and C<dTHX>, and
their variants.
+=for apidoc Amnh||aTHX
+=for apidoc Amnh||aTHX_
+=for apidoc Amnh||dTHX
+=for apidoc Amnh||pTHX
+=for apidoc Amnh||pTHX_
+
When Perl is built without options that set PERL_IMPLICIT_CONTEXT, there is no
first argument containing the interpreter's context. The trailing underscore
in the pTHX_ macro indicates that the macro expansion needs a comma
=head2 So what happened to dTHR?
+=for apidoc Amnh||dTHR
+
C<dTHR> was introduced in perl 5.005 to support the older thread model.
The older thread model now uses the C<THX> mechanism to pass context
pointers around, so C<dTHR> is not useful any more. Perl 5.6.0 and
Apd |SV** |av_fetch |AV* ar|I32 key|I32 lval
-The second column is the return type, the third column the name. Columns
-after that are the arguments. The first column is a set of flags:
-
-=over 3
-
-=item A
-
-This function is a part of the public
-API. All such functions should also
-have 'd', very few do not.
-
-=item p
-
-This function has a C<Perl_> prefix; i.e. it is defined as
-C<Perl_av_fetch>.
-
-=item d
-
-This function has documentation using the C<apidoc> feature which we'll
-look at in a second. Some functions have 'd' but not 'A'; docs are good.
-
-=back
-
-Other available flags are:
-
-=over 3
-
-=item s
-
-This is a static function and is defined as C<STATIC S_whatever>, and
-usually called within the sources as C<whatever(...)>.
-
-=item n
-
-This does not need an interpreter context, so the definition has no
-C<pTHX>, and it follows that callers don't use C<aTHX>. (See
-L</Background and PERL_IMPLICIT_CONTEXT>.)
-
-=item r
-
-This function never returns; C<croak>, C<exit> and friends.
-
-=item f
-
-This function takes a variable number of arguments, C<printf> style.
-The argument list should end with C<...>, like this:
-
- Afprd |void |croak |const char* pat|...
-
-=item M
-
-This function is part of the experimental development API, and may change
-or disappear without notice.
-
-=item o
-
-This function should not have a compatibility macro to define, say,
-C<Perl_parse> to C<parse>. It must be called as C<Perl_parse>.
-
-=item x
-
-This function isn't exported out of the Perl core.
-
-=item m
-
-This is implemented as a macro.
-
-=item X
-
-This function is explicitly exported.
-
-=item E
-
-This function is visible to extensions included in the Perl core.
-
-=item b
-
-Binary backward compatibility; this function is a macro but also has
-a C<Perl_> implementation (which is exported).
-
-=item others
-
-See the comments at the top of C<embed.fnc> for others.
-
-=back
+The first column is a set of flags, the second column the return type,
+the third column the name. Columns after that are the arguments.
+The flags are documented at the top of F<embed.fnc>.
If you edit F<embed.pl> or F<embed.fnc>, you will need to run
C<make regen_headers> to force a rebuild of F<embed.h> and other
NVff NV %f-like
NVgf NV %g-like
+=for apidoc Amnh||IVdf
+=for apidoc Amnh||UVuf
+=for apidoc Amnh||UVof
+=for apidoc Amnh||UVxf
+=for apidoc Amnh||NVef
+=for apidoc Amnh||NVff
+=for apidoc Amnh||NVgf
+
These will take care of 64-bit integers and long doubles.
For example:
- printf("IV is %"IVdf"\n", iv);
+ printf("IV is %" IVdf "\n", iv);
-The IVdf will expand to whatever is the correct format for the IVs.
+The C<IVdf> will expand to whatever is the correct format for the IVs.
+Note that the spaces are required around the format in case the code is
+compiled with C++, to maintain compliance with its standard.
Note that there are different "long doubles": Perl will use
whatever the compiler has.
If you are printing addresses of pointers, use UVxf combined
with PTR2UV(), do not use %lx or %p.
+=head2 Formatted Printing of SvPVs
+
+If you just want the bytes printed in a NUL-terminated string, you can
+just use C<%s> (assuming they are all printables). But if there is a
+possibility the value will be encoded as UTF-8, you should instead use
+the C<UTF8f> format. And as its parameter, use the C<UTF8fARG()> macro.
+Below is a general example using the SV C<err_msg> which is known to
+contain a string and not need magic handling:
+
+ Perl_croak(aTHX_ "This croaked because: " UTF8f "\n",
+ UTF8fARG(SvUTF8(err_msg),
+ SvCUR(err_msg),
+ SvPVX(err_msg)));
+
+The first parameter to C<UTF8fARG> is a boolean: 1 if the string is in
+UTF-8; 0 if bytes.
+The second parameter is the number of bytes in the string to print.
+And the third and final parameter is a pointer to the first byte in the
+string.
+
+=head2 Formatted Printing of C<Size_t> and C<SSize_t>
+
+The most general way to do this is to cast them to a UV or IV, and
+print as in the
+L<previous section|/Formatted Printing of IVs, UVs, and NVs>.
+
+But if you're using C<PerlIO_printf()>, it's less typing and visual
+clutter to use the C<"%z"> length modifier (for I<siZe>):
+
+ PerlIO_printf("STRLEN is %zu\n", len);
+
+This modifier is not portable, so its use should be restricted to
+C<PerlIO_printf()>.
+
=head2 Pointer-To-Integer and Integer-To-Pointer
Because pointer size does not necessarily equal integer size,
PTR2NV(pointer)
INT2PTR(pointertotype, integer)
+=for apidoc Amh|void *|INT2PTR|type|int value
+=for apidoc Amh|UV|PTR2UV|void *
+=for apidoc Amh|IV|PTR2IV|void *
+=for apidoc Amh|NV|PTR2NV|void *
+
For example:
IV iv = ...;
=for apidoc sv_setiv
Copies an integer into the given SV. Does not handle 'set' magic. See
- C<sv_setiv_mg>.
+ L<perlapi/sv_setiv_mg>.
=cut
*/
character like this (the C<UTF8_IS_INVARIANT()> is a macro that tests
whether the byte is encoded as a single byte even in UTF-8):
- U8 *utf;
- U8 *utf_end; /* 1 beyond buffer pointed to by utf */
- UV uv; /* Note: a UV, not a U8, not a char */
- STRLEN len; /* length of character in bytes */
+ U8 *utf; /* Initialize this to point to the beginning of the
+ sequence to convert */
+ U8 *utf_end; /* Initialize this to 1 beyond the end of the sequence
+ pointed to by 'utf' */
+ UV uv; /* Returned code point; note: a UV, not a U8, not a
+ char */
+ STRLEN len; /* Returned length of character in bytes */
if (!UTF8_IS_INVARIANT(*utf))
/* Must treat this as UTF-8 */
C<B::Generate> directly supports the creation of custom ops by name.
+=head1 Stacks
+
+Descriptions above occasionally refer to "the stack", but there are in fact
+many stack-like data structures within the perl interpreter. When otherwise
+unqualified, "the stack" usually refers to the value stack.
+
+The various stacks have different purposes, and operate in slightly different
+ways. Their differences are noted below.
+
+=head2 Value Stack
+
+This stack stores the values that regular perl code is operating on, usually
+intermediate values of expressions within a statement. The stack itself is
+formed of an array of SV pointers.
+
+The base of this stack is pointed to by the interpreter variable
+C<PL_stack_base>, of type C<SV **>.
+
+The head of the stack is C<PL_stack_sp>, and points to the most
+recently-pushed item.
+
+Items are pushed to the stack by using the C<PUSHs()> macro or its variants
+described above; C<XPUSHs()>, C<mPUSHs()>, C<mXPUSHs()> and the typed
+versions. Note carefully that the non-C<X> versions of these macros do not
+check the size of the stack and assume it to be big enough. These must be
+paired with a suitable check of the stack's size, such as the C<EXTEND> macro
+to ensure it is large enough. For example
+
+ EXTEND(SP, 4);
+ mPUSHi(10);
+ mPUSHi(20);
+ mPUSHi(30);
+ mPUSHi(40);
+
+This is slightly more performant than making four separate checks in four
+separate C<mXPUSHi()> calls.
+
+As a further performance optimisation, the various C<PUSH> macros all operate
+using a local variable C<SP>, rather than the interpreter-global variable
+C<PL_stack_sp>. This variable is declared by the C<dSP> macro - though it is
+normally implied by XSUBs and similar so it is rare you have to consider it
+directly. Once declared, the C<PUSH> macros will operate only on this local
+variable, so before invoking any other perl core functions you must use the
+C<PUTBACK> macro to return the value from the local C<SP> variable back to
+the interpreter variable. Similarly, after calling a perl core function which
+may have had reason to move the stack or push/pop values to it, you must use
+the C<SPAGAIN> macro which refreshes the local C<SP> value back from the
+interpreter one.
+
+Items are popped from the stack by using the C<POPs> macro or its typed
+versions, There is also a macro C<TOPs> that inspects the topmost item without
+removing it.
+
+Note specifically that SV pointers on the value stack do not contribute to the
+overall reference count of the xVs being referred to. If newly-created xVs are
+being pushed to the stack you must arrange for them to be destroyed at a
+suitable time; usually by using one of the C<mPUSH*> macros or C<sv_2mortal()>
+to mortalise the xV.
+
+=head2 Mark Stack
+
+The value stack stores individual perl scalar values as temporaries between
+expressions. Some perl expressions operate on entire lists; for that purpose
+we need to know where on the stack each list begins. This is the purpose of the
+mark stack.
+
+The mark stack stores integers as I32 values, which are the height of the
+value stack at the time before the list began; thus the mark itself actually
+points to the value stack entry one before the list. The list itself starts at
+C<mark + 1>.
+
+The base of this stack is pointed to by the interpreter variable
+C<PL_markstack>, of type C<I32 *>.
+
+The head of the stack is C<PL_markstack_ptr>, and points to the most
+recently-pushed item.
+
+Items are pushed to the stack by using the C<PUSHMARK()> macro. Even though
+the stack itself stores (value) stack indices as integers, the C<PUSHMARK>
+macro should be given a stack pointer directly; it will calculate the index
+offset by comparing to the C<PL_stack_sp> variable. Thus almost always the
+code to perform this is
+
+ PUSHMARK(SP);
+
+Items are popped from the stack by the C<POPMARK> macro. There is also a macro
+C<TOPMARK> that inspects the topmost item without removing it. These macros
+return I32 index values directly. There is also the C<dMARK> macro which
+declares a new SV double-pointer variable, called C<mark>, which points at the
+marked stack slot; this is the usual macro that C code will use when operating
+on lists given on the stack.
+
+As noted above, the C<mark> variable itself will point at the most recently
+pushed value on the value stack before the list begins, and so the list itself
+starts at C<mark + 1>. The values of the list may be iterated by code such as
+
+ for(SV **svp = mark + 1; svp <= PL_stack_sp; svp++) {
+ SV *item = *svp;
+ ...
+ }
+
+Note specifically in the case that the list is already empty, C<mark> will
+equal C<PL_stack_sp>.
+
+Because the C<mark> variable is converted to a pointer on the value stack,
+extra care must be taken if C<EXTEND> or any of the C<XPUSH> macros are
+invoked within the function, because the stack may need to be moved to
+extend it and so the existing pointer will now be invalid. If this may be a
+problem, a possible solution is to track the mark offset as an integer and
+track the mark itself later on after the stack had been moved.
+
+ I32 markoff = POPMARK;
+
+ ...
+
+ SP **mark = PL_stack_base + markoff;
+
+=head2 Temporaries Stack
+
+As noted above, xV references on the main value stack do not contribute to the
+reference count of an xV, and so another mechanism is used to track when
+temporary values which live on the stack must be released. This is the job of
+the temporaries stack.
+
+The temporaries stack stores pointers to xVs whose reference counts will be
+decremented soon.
+
+The base of this stack is pointed to by the interpreter variable
+C<PL_tmps_stack>, of type C<SV **>.
+
+The head of the stack is indexed by C<PL_tmps_ix>, an integer which stores the
+index in the array of the most recently-pushed item.
+
+There is no public API to directly push items to the temporaries stack. Instead,
+the API function C<sv_2mortal()> is used to mortalize an xV, adding its
+address to the temporaries stack.
+
+Likewise, there is no public API to read values from the temporaries stack.
+Instead. the macros C<SAVETMPS> and C<FREETPMS> are used. The C<SAVETMPS>
+macro establishes the base levels of the temporaries stack, by capturing the
+current value of C<PL_tmps_ix> into C<PL_tmps_floor> and saving the previous
+value to the save stack. Thereafter, whenever C<FREETMPS> is invoked all of
+the temporaries that have been pushed since that level are reclaimed.
+
+While it is common to see these two macros in pairs within an C<ENTER>/
+C<LEAVE> pair, it is not necessary to match them. It is permitted to invoke
+C<FREETMPS> multiple times since the most recent C<SAVETMPS>; for example in a
+loop iterating over elements of a list. While you can invoke C<SAVETMPS>
+multiple times within a scope pair, it is unlikely to be useful. Subsequent
+invocations will move the temporaries floor further up, thus effectively
+trapping the existing temporaries to only be released at the end of the scope.
+
+=head2 Save Stack
+
+The save stack is used by perl to implement the C<local> keyword and other
+similar behaviours; any cleanup operations that need to be performed when
+leaving the current scope. Items pushed to this stack generally capture the
+current value of some internal variable or state, which will be restored when
+the scope is unwound due to leaving, C<return>, C<die>, C<goto> or other
+reasons.
+
+Whereas other perl internal stacks store individual items all of the same type
+(usually SV pointers or integers), the items pushed to the save stack are
+formed of many different types, having multiple fields to them. For example,
+the C<SAVEt_INT> type needs to store both the address of the C<int> variable
+to restore, and the value to restore it to. This information could have been
+stored using fields of a C<struct>, but would have to be large enough to store
+three pointers in the largest case, which would waste a lot of space in most
+of the smaller cases.
+
+Instead, the stack stores information in a variable-length encoding of C<ANY>
+structures. The final value pushed is stored in the C<UV> field which encodes
+the kind of item held by the preceeding items; the count and types of which
+will depend on what kind of item is being stored. The kind field is pushed
+last because that will be the first field to be popped when unwinding items
+from the stack.
+
+The base of this stack is pointed to by the interpreter variable
+C<PL_savestack>, of type C<ANY *>.
+
+The head of the stack is indexed by C<PL_savestack_ix>, an integer which
+stores the index in the array at which the next item should be pushed. (Note
+that this is different to most other stacks, which reference the most
+recently-pushed item).
+
+Items are pushed to the save stack by using the various C<SAVE...()> macros.
+Many of these macros take a variable and store both its address and current
+value on the save stack, ensuring that value gets restored on scope exit.
+
+ SAVEI8(i8)
+ SAVEI16(i16)
+ SAVEI32(i32)
+ SAVEINT(i)
+ ...
+
+There are also a variety of other special-purpose macros which save particular
+types or values of interest. C<SAVETMPS> has already been mentioned above.
+Others include C<SAVEFREEPV> which arranges for a PV (i.e. a string buffer) to
+be freed, or C<SAVEDESTRUCTOR> which arranges for a given function pointer to
+be invoked on scope exit. A full list of such macros can be found in
+F<scope.h>.
+
+There is no public API for popping individual values or items from the save
+stack. Instead, via the scope stack, the C<ENTER> and C<LEAVE> pair form a way
+to start and stop nested scopes. Leaving a nested scope via C<LEAVE> will
+restore all of the saved values that had been pushed since the most recent
+C<ENTER>.
+
+=head2 Scope Stack
+
+As with the mark stack to the value stack, the scope stack forms a pair with
+the save stack. The scope stack stores the height of the scope stack at which
+nested scopes begin, and allows the save stack to be unwound back to that
+point when the scope is left.
+
+When perl is built with debugging enabled, there is a second part to this
+stack storing human-readable string names describing the type of stack
+context. Each push operation saves the name as well as the height of the save
+stack, and each pop operation checks the topmost name with what is expected,
+causing an assertion failure if the name does not match.
+
+The base of this stack is pointed to by the interpreter variable
+C<PL_scopestack>, of type C<I32 *>. If enabled, the scope stack names are
+stored in a separate array pointed to by C<PL_scopestack_name>, of type
+C<const char **>.
+
+The head of the stack is indexed by C<PL_scopestack_ix>, an integer which
+stores the index of the array or arrays at which the next item should be
+pushed. (Note that this is different to most other stacks, which reference the
+most recently-pushed item).
+
+Values are pushed to the scope stack using the C<ENTER> macro, which begins a
+new nested scope. Any items pushed to the save stack are then restored at the
+next nested invocation of the C<LEAVE> macro.
+
+=head1 Dynamic Scope and the Context Stack
+
+B<Note:> this section describes a non-public internal API that is subject
+to change without notice.
+
+=head2 Introduction to the context stack
+
+In Perl, dynamic scoping refers to the runtime nesting of things like
+subroutine calls, evals etc, as well as the entering and exiting of block
+scopes. For example, the restoring of a C<local>ised variable is
+determined by the dynamic scope.
+
+Perl tracks the dynamic scope by a data structure called the context
+stack, which is an array of C<PERL_CONTEXT> structures, and which is
+itself a big union for all the types of context. Whenever a new scope is
+entered (such as a block, a C<for> loop, or a subroutine call), a new
+context entry is pushed onto the stack. Similarly when leaving a block or
+returning from a subroutine call etc. a context is popped. Since the
+context stack represents the current dynamic scope, it can be searched.
+For example, C<next LABEL> searches back through the stack looking for a
+loop context that matches the label; C<return> pops contexts until it
+finds a sub or eval context or similar; C<caller> examines sub contexts on
+the stack.
+
+Each context entry is labelled with a context type, C<cx_type>. Typical
+context types are C<CXt_SUB>, C<CXt_EVAL> etc., as well as C<CXt_BLOCK>
+and C<CXt_NULL> which represent a basic scope (as pushed by C<pp_enter>)
+and a sort block. The type determines which part of the context union are
+valid.
+
+The main division in the context struct is between a substitution scope
+(C<CXt_SUBST>) and block scopes, which are everything else. The former is
+just used while executing C<s///e>, and won't be discussed further
+here.
+
+All the block scope types share a common base, which corresponds to
+C<CXt_BLOCK>. This stores the old values of various scope-related
+variables like C<PL_curpm>, as well as information about the current
+scope, such as C<gimme>. On scope exit, the old variables are restored.
+
+Particular block scope types store extra per-type information. For
+example, C<CXt_SUB> stores the currently executing CV, while the various
+for loop types might hold the original loop variable SV. On scope exit,
+the per-type data is processed; for example the CV has its reference count
+decremented, and the original loop variable is restored.
+
+The macro C<cxstack> returns the base of the current context stack, while
+C<cxstack_ix> is the index of the current frame within that stack.
+
+In fact, the context stack is actually part of a stack-of-stacks system;
+whenever something unusual is done such as calling a C<DESTROY> or tie
+handler, a new stack is pushed, then popped at the end.
+
+Note that the API described here changed considerably in perl 5.24; prior
+to that, big macros like C<PUSHBLOCK> and C<POPSUB> were used; in 5.24
+they were replaced by the inline static functions described below. In
+addition, the ordering and detail of how these macros/function work
+changed in many ways, often subtly. In particular they didn't handle
+saving the savestack and temps stack positions, and required additional
+C<ENTER>, C<SAVETMPS> and C<LEAVE> compared to the new functions. The
+old-style macros will not be described further.
+
+
+=head2 Pushing contexts
+
+For pushing a new context, the two basic functions are
+C<cx = cx_pushblock()>, which pushes a new basic context block and returns
+its address, and a family of similar functions with names like
+C<cx_pushsub(cx)> which populate the additional type-dependent fields in
+the C<cx> struct. Note that C<CXt_NULL> and C<CXt_BLOCK> don't have their
+own push functions, as they don't store any data beyond that pushed by
+C<cx_pushblock>.
+
+The fields of the context struct and the arguments to the C<cx_*>
+functions are subject to change between perl releases, representing
+whatever is convenient or efficient for that release.
+
+A typical context stack pushing can be found in C<pp_entersub>; the
+following shows a simplified and stripped-down example of a non-XS call,
+along with comments showing roughly what each function does.
+
+ dMARK;
+ U8 gimme = GIMME_V;
+ bool hasargs = cBOOL(PL_op->op_flags & OPf_STACKED);
+ OP *retop = PL_op->op_next;
+ I32 old_ss_ix = PL_savestack_ix;
+ CV *cv = ....;
+
+ /* ... make mortal copies of stack args which are PADTMPs here ... */
+
+ /* ... do any additional savestack pushes here ... */
+
+ /* Now push a new context entry of type 'CXt_SUB'; initially just
+ * doing the actions common to all block types: */
+
+ cx = cx_pushblock(CXt_SUB, gimme, MARK, old_ss_ix);
+
+ /* this does (approximately):
+ CXINC; /* cxstack_ix++ (grow if necessary) */
+ cx = CX_CUR(); /* and get the address of new frame */
+ cx->cx_type = CXt_SUB;
+ cx->blk_gimme = gimme;
+ cx->blk_oldsp = MARK - PL_stack_base;
+ cx->blk_oldsaveix = old_ss_ix;
+ cx->blk_oldcop = PL_curcop;
+ cx->blk_oldmarksp = PL_markstack_ptr - PL_markstack;
+ cx->blk_oldscopesp = PL_scopestack_ix;
+ cx->blk_oldpm = PL_curpm;
+ cx->blk_old_tmpsfloor = PL_tmps_floor;
+
+ PL_tmps_floor = PL_tmps_ix;
+ */
+
+
+ /* then update the new context frame with subroutine-specific info,
+ * such as the CV about to be executed: */
+
+ cx_pushsub(cx, cv, retop, hasargs);
+
+ /* this does (approximately):
+ cx->blk_sub.cv = cv;
+ cx->blk_sub.olddepth = CvDEPTH(cv);
+ cx->blk_sub.prevcomppad = PL_comppad;
+ cx->cx_type |= (hasargs) ? CXp_HASARGS : 0;
+ cx->blk_sub.retop = retop;
+ SvREFCNT_inc_simple_void_NN(cv);
+ */
+
+Note that C<cx_pushblock()> sets two new floors: for the args stack (to
+C<MARK>) and the temps stack (to C<PL_tmps_ix>). While executing at this
+scope level, every C<nextstate> (amongst others) will reset the args and
+tmps stack levels to these floors. Note that since C<cx_pushblock> uses
+the current value of C<PL_tmps_ix> rather than it being passed as an arg,
+this dictates at what point C<cx_pushblock> should be called. In
+particular, any new mortals which should be freed only on scope exit
+(rather than at the next C<nextstate>) should be created first.
+
+Most callers of C<cx_pushblock> simply set the new args stack floor to the
+top of the previous stack frame, but for C<CXt_LOOP_LIST> it stores the
+items being iterated over on the stack, and so sets C<blk_oldsp> to the
+top of these items instead. Note that, contrary to its name, C<blk_oldsp>
+doesn't always represent the value to restore C<PL_stack_sp> to on scope
+exit.
+
+Note the early capture of C<PL_savestack_ix> to C<old_ss_ix>, which is
+later passed as an arg to C<cx_pushblock>. In the case of C<pp_entersub>,
+this is because, although most values needing saving are stored in fields
+of the context struct, an extra value needs saving only when the debugger
+is running, and it doesn't make sense to bloat the struct for this rare
+case. So instead it is saved on the savestack. Since this value gets
+calculated and saved before the context is pushed, it is necessary to pass
+the old value of C<PL_savestack_ix> to C<cx_pushblock>, to ensure that the
+saved value gets freed during scope exit. For most users of
+C<cx_pushblock>, where nothing needs pushing on the save stack,
+C<PL_savestack_ix> is just passed directly as an arg to C<cx_pushblock>.
+
+Note that where possible, values should be saved in the context struct
+rather than on the save stack; it's much faster that way.
+
+Normally C<cx_pushblock> should be immediately followed by the appropriate
+C<cx_pushfoo>, with nothing between them; this is because if code
+in-between could die (e.g. a warning upgraded to fatal), then the context
+stack unwinding code in C<dounwind> would see (in the example above) a
+C<CXt_SUB> context frame, but without all the subroutine-specific fields
+set, and crashes would soon ensue.
+
+Where the two must be separate, initially set the type to C<CXt_NULL> or
+C<CXt_BLOCK>, and later change it to C<CXt_foo> when doing the
+C<cx_pushfoo>. This is exactly what C<pp_enteriter> does, once it's
+determined which type of loop it's pushing.
+
+=head2 Popping contexts
+
+Contexts are popped using C<cx_popsub()> etc. and C<cx_popblock()>. Note
+however, that unlike C<cx_pushblock>, neither of these functions actually
+decrement the current context stack index; this is done separately using
+C<CX_POP()>.
+
+There are two main ways that contexts are popped. During normal execution
+as scopes are exited, functions like C<pp_leave>, C<pp_leaveloop> and
+C<pp_leavesub> process and pop just one context using C<cx_popfoo> and
+C<cx_popblock>. On the other hand, things like C<pp_return> and C<next>
+may have to pop back several scopes until a sub or loop context is found,
+and exceptions (such as C<die>) need to pop back contexts until an eval
+context is found. Both of these are accomplished by C<dounwind()>, which
+is capable of processing and popping all contexts above the target one.
+
+Here is a typical example of context popping, as found in C<pp_leavesub>
+(simplified slightly):
+
+ U8 gimme;
+ PERL_CONTEXT *cx;
+ SV **oldsp;
+ OP *retop;
+
+ cx = CX_CUR();
+
+ gimme = cx->blk_gimme;
+ oldsp = PL_stack_base + cx->blk_oldsp; /* last arg of previous frame */
+
+ if (gimme == G_VOID)
+ PL_stack_sp = oldsp;
+ else
+ leave_adjust_stacks(oldsp, oldsp, gimme, 0);
+
+ CX_LEAVE_SCOPE(cx);
+ cx_popsub(cx);
+ cx_popblock(cx);
+ retop = cx->blk_sub.retop;
+ CX_POP(cx);
+
+ return retop;
+
+The steps above are in a very specific order, designed to be the reverse
+order of when the context was pushed. The first thing to do is to copy
+and/or protect any any return arguments and free any temps in the current
+scope. Scope exits like an rvalue sub normally return a mortal copy of
+their return args (as opposed to lvalue subs). It is important to make
+this copy before the save stack is popped or variables are restored, or
+bad things like the following can happen:
+
+ sub f { my $x =...; $x } # $x freed before we get to copy it
+ sub f { /(...)/; $1 } # PL_curpm restored before $1 copied
+
+Although we wish to free any temps at the same time, we have to be careful
+not to free any temps which are keeping return args alive; nor to free the
+temps we have just created while mortal copying return args. Fortunately,
+C<leave_adjust_stacks()> is capable of making mortal copies of return args,
+shifting args down the stack, and only processing those entries on the
+temps stack that are safe to do so.
+
+In void context no args are returned, so it's more efficient to skip
+calling C<leave_adjust_stacks()>. Also in void context, a C<nextstate> op
+is likely to be imminently called which will do a C<FREETMPS>, so there's
+no need to do that either.
+
+The next step is to pop savestack entries: C<CX_LEAVE_SCOPE(cx)> is just
+defined as C<< LEAVE_SCOPE(cx->blk_oldsaveix) >>. Note that during the
+popping, it's possible for perl to call destructors, call C<STORE> to undo
+localisations of tied vars, and so on. Any of these can die or call
+C<exit()>. In this case, C<dounwind()> will be called, and the current
+context stack frame will be re-processed. Thus it is vital that all steps
+in popping a context are done in such a way to support reentrancy. The
+other alternative, of decrementing C<cxstack_ix> I<before> processing the
+frame, would lead to leaks and the like if something died halfway through,
+or overwriting of the current frame.
+
+C<CX_LEAVE_SCOPE> itself is safely re-entrant: if only half the savestack
+items have been popped before dying and getting trapped by eval, then the
+C<CX_LEAVE_SCOPE>s in C<dounwind> or C<pp_leaveeval> will continue where
+the first one left off.
+
+The next step is the type-specific context processing; in this case
+C<cx_popsub>. In part, this looks like:
+
+ cv = cx->blk_sub.cv;
+ CvDEPTH(cv) = cx->blk_sub.olddepth;
+ cx->blk_sub.cv = NULL;
+ SvREFCNT_dec(cv);
+
+where its processing the just-executed CV. Note that before it decrements
+the CV's reference count, it nulls the C<blk_sub.cv>. This means that if
+it re-enters, the CV won't be freed twice. It also means that you can't
+rely on such type-specific fields having useful values after the return
+from C<cx_popfoo>.
+
+Next, C<cx_popblock> restores all the various interpreter vars to their
+previous values or previous high water marks; it expands to:
+
+ PL_markstack_ptr = PL_markstack + cx->blk_oldmarksp;
+ PL_scopestack_ix = cx->blk_oldscopesp;
+ PL_curpm = cx->blk_oldpm;
+ PL_curcop = cx->blk_oldcop;
+ PL_tmps_floor = cx->blk_old_tmpsfloor;
+
+Note that it I<doesn't> restore C<PL_stack_sp>; as mentioned earlier,
+which value to restore it to depends on the context type (specifically
+C<for (list) {}>), and what args (if any) it returns; and that will
+already have been sorted out earlier by C<leave_adjust_stacks()>.
+
+Finally, the context stack pointer is actually decremented by C<CX_POP(cx)>.
+After this point, it's possible that that the current context frame could
+be overwritten by other contexts being pushed. Although things like ties
+and C<DESTROY> are supposed to work within a new context stack, it's best
+not to assume this. Indeed on debugging builds, C<CX_POP(cx)> deliberately
+sets C<cx> to null to detect code that is still relying on the field
+values in that context frame. Note in the C<pp_leavesub()> example above,
+we grab C<blk_sub.retop> I<before> calling C<CX_POP>.
+
+=head2 Redoing contexts
+
+Finally, there is C<cx_topblock(cx)>, which acts like a super-C<nextstate>
+as regards to resetting various vars to their base values. It is used in
+places like C<pp_next>, C<pp_redo> and C<pp_goto> where rather than
+exiting a scope, we want to re-initialise the scope. As well as resetting
+C<PL_stack_sp> like C<nextstate>, it also resets C<PL_markstack_ptr>,
+C<PL_scopestack_ix> and C<PL_curpm>. Note that it doesn't do a
+C<FREETMPS>.
+
+
+=head1 Slab-based operator allocation
+
+B<Note:> this section describes a non-public internal API that is subject
+to change without notice.
+
+Perl's internal error-handling mechanisms implement C<die> (and its internal
+equivalents) using longjmp. If this occurs during lexing, parsing or
+compilation, we must ensure that any ops allocated as part of the compilation
+process are freed. (Older Perl versions did not adequately handle this
+situation: when failing a parse, they would leak ops that were stored in
+C C<auto> variables and not linked anywhere else.)
+
+To handle this situation, Perl uses I<op slabs> that are attached to the
+currently-compiling CV. A slab is a chunk of allocated memory. New ops are
+allocated as regions of the slab. If the slab fills up, a new one is created
+(and linked from the previous one). When an error occurs and the CV is freed,
+any ops remaining are freed.
+
+Each op is preceded by two pointers: one points to the next op in the slab, and
+the other points to the slab that owns it. The next-op pointer is needed so
+that Perl can iterate over a slab and free all its ops. (Op structures are of
+different sizes, so the slab's ops can't merely be treated as a dense array.)
+The slab pointer is needed for accessing a reference count on the slab: when
+the last op on a slab is freed, the slab itself is freed.
+
+The slab allocator puts the ops at the end of the slab first. This will tend to
+allocate the leaves of the op tree first, and the layout will therefore
+hopefully be cache-friendly. In addition, this means that there's no need to
+store the size of the slab (see below on why slabs vary in size), because Perl
+can follow pointers to find the last op.
+
+It might seem possible eliminate slab reference counts altogether, by having
+all ops implicitly attached to C<PL_compcv> when allocated and freed when the
+CV is freed. That would also allow C<op_free> to skip C<FreeOp> altogether, and
+thus free ops faster. But that doesn't work in those cases where ops need to
+survive beyond their CVs, such as re-evals.
+
+The CV also has to have a reference count on the slab. Sometimes the first op
+created is immediately freed. If the reference count of the slab reaches 0,
+then it will be freed with the CV still pointing to it.
+
+CVs use the C<CVf_SLABBED> flag to indicate that the CV has a reference count
+on the slab. When this flag is set, the slab is accessible via C<CvSTART> when
+C<CvROOT> is not set, or by subtracting two pointers C<(2*sizeof(I32 *))> from
+C<CvROOT> when it is set. The alternative to this approach of sneaking the slab
+into C<CvSTART> during compilation would be to enlarge the C<xpvcv> struct by
+another pointer. But that would make all CVs larger, even though slab-based op
+freeing is typically of benefit only for programs that make significant use of
+string eval.
+
+When the C<CVf_SLABBED> flag is set, the CV takes responsibility for freeing
+the slab. If C<CvROOT> is not set when the CV is freed or undeffed, it is
+assumed that a compilation error has occurred, so the op slab is traversed and
+all the ops are freed.
+
+Under normal circumstances, the CV forgets about its slab (decrementing the
+reference count) when the root is attached. So the slab reference counting that
+happens when ops are freed takes care of freeing the slab. In some cases, the
+CV is told to forget about the slab (C<cv_forget_slab>) precisely so that the
+ops can survive after the CV is done away with.
+
+Forgetting the slab when the root is attached is not strictly necessary, but
+avoids potential problems with C<CvROOT> being written over. There is code all
+over the place, both in core and on CPAN, that does things with C<CvROOT>, so
+forgetting the slab makes things more robust and avoids potential problems.
+
+Since the CV takes ownership of its slab when flagged, that flag is never
+copied when a CV is cloned, as one CV could free a slab that another CV still
+points to, since forced freeing of ops ignores the reference count (but asserts
+that it looks right).
+
+To avoid slab fragmentation, freed ops are marked as freed and attached to the
+slab's freed chain (an idea stolen from DBM::Deep). Those freed ops are reused
+when possible. Not reusing freed ops would be simpler, but it would result in
+significantly higher memory usage for programs with large C<if (DEBUG) {...}>
+blocks.
+
+C<SAVEFREEOP> is slightly problematic under this scheme. Sometimes it can cause
+an op to be freed after its CV. If the CV has forcibly freed the ops on its
+slab and the slab itself, then we will be fiddling with a freed slab. Making
+C<SAVEFREEOP> a no-op doesn't help, as sometimes an op can be savefreed when
+there is no compilation error, so the op would never be freed. It holds
+a reference count on the slab, so the whole slab would leak. So C<SAVEFREEOP>
+now sets a special flag on the op (C<< ->op_savefree >>). The forced freeing of
+ops after a compilation error won't free any ops thus marked.
+
+Since many pieces of code create tiny subroutines consisting of only a few ops,
+and since a huge slab would be quite a bit of baggage for those to carry
+around, the first slab is always very small. To avoid allocating too many
+slabs for a single CV, each subsequent slab is twice the size of the previous.
+
+Smartmatch expects to be able to allocate an op at run time, run it, and then
+throw it away. For that to work the op is simply malloced when PL_compcv hasn't
+been set up. So all slab-allocated ops are marked as such (C<< ->op_slabbed >>),
+to distinguish them from malloced ops.
+
+
=head1 AUTHORS
Until May 1997, this document was maintained by Jeff Okamoto
https://perl5.git.perl.org / perl5.git / blobdiff