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
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.
=head2 Hash API Extensions
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 */
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 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,
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
If you are printing addresses of pointers, use UVxf combined
with PTR2UV(), do not use %lx or %p.
+=head2 Formatted Printing of Size_t and 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,
=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
*/
the SV is not enough to copy the UTF8 flags, even less right is just
passing a S<C<char *>> to an XS function.
-For full generality, use the L<perlapi/DO_UTF8> macro to see if the
+For full generality, use the L<C<DO_UTF8>|perlapi/DO_UTF8> macro to see if the
string in an SV is to be I<treated> as UTF-8. This takes into account
if the call to the XS function is being made from within the scope of
L<S<C<use bytes>>|bytes>. If so, the underlying bytes that comprise the
C<B::Generate> directly supports the creation of custom ops by name.
+
+=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 AUTHORS
Until May 1997, this document was maintained by Jeff Okamoto
https://perl5.git.perl.org / perl5.git / blobdiff