+
+=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>.
+
+