develooper Front page | perl.perl5.porters | Postings from September 2019

Re: [WIP-PATCH] Document the various interpreter stacks

Thread Previous | Thread Next
From:
Tony Cook
Date:
September 19, 2019 23:22
Subject:
Re: [WIP-PATCH] Document the various interpreter stacks
Message ID:
20190919232201.bgxhs5bbldfb3sdq@mars.tony.develop-help.com
This all looks good, though I have a couple of suggestions.

On Wed, Sep 18, 2019 at 04:28:34PM +0100, Paul "LeoNerd" Evans wrote:
> +=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.
> +
> +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.

This should mention EXTEND().

It might be worth mentioning PUSHSTACKi() too.

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

It might be worth mentioning that mark may become invalid if the value
stack is extended (see 57bd6600 for example.)

Tony

Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About