1N/Aperlintern - autogenerated documentation of purely B<internal>
1N/AThis file is the autogenerated documentation of functions in the
1N/APerl interpreter that are documented using Perl's internal documentation
1N/Aformat but are not marked as part of the Perl API. In other words,
1N/AB<they are not for use in extensions>!
1N/A=head1 CV reference counts and CvOUTSIDE
1N/AEach CV has a pointer, C<CvOUTSIDE()>, to its lexically enclosing
1N/ACV (if any). Because pointers to anonymous sub prototypes are
1N/Astored in C<&> pad slots, it is a possible to get a circular reference,
1N/Awith the parent pointing to the child and vice-versa. To avoid the
1N/Aensuing memory leak, we do not increment the reference count of the CV
1N/Apointed to by C<CvOUTSIDE> in the I<one specific instance> that the parent
1N/Ahas a C<&> pad slot pointing back to us. In this case, we set the
1N/AC<CvWEAKOUTSIDE> flag in the child. This allows us to determine under what
1N/Acircumstances we should decrement the refcount of the parent when freeing
1N/AThere is a further complication with non-closure anonymous subs (ie those
1N/Athat do not refer to any lexicals outside that sub). In this case, the
1N/Aanonymous prototype is shared rather than being cloned. This has the
1N/Aconsequence that the parent may be freed while there are still active
1N/A BEGIN { $a = sub { eval '$x' } }
1N/AIn this case, the BEGIN is freed immediately after execution since there
1N/Aare no active references to it: the anon sub prototype has
1N/AC<CvWEAKOUTSIDE> set since it's not a closure, and $a points to the same
1N/ACV, so it doesn't contribute to BEGIN's refcount either. When $a is
1N/Aexecuted, the C<eval '$x'> causes the chain of C<CvOUTSIDE>s to be followed,
1N/Aand the freed BEGIN is accessed.
1N/ATo avoid this, whenever a CV and its associated pad is freed, any
1N/AC<&> entries in the pad are explicitly removed from the pad, and if the
1N/Arefcount of the pointed-to anon sub is still positive, then that
1N/Achild's C<CvOUTSIDE> is set to point to its grandparent. This will only
1N/Aoccur in the single specific case of a non-closure anon prototype
1N/Ahaving one or more active references (such as C<$a> above).
1N/AOne other thing to consider is that a CV may be merely undefined
1N/Arather than freed, eg C<undef &foo>. In this case, its refcount may
1N/Anot have reached zero, but we still delete its pad and its C<CvROOT> etc.
1N/ASince various children may still have their C<CvOUTSIDE> pointing at this
1N/Aundefined CV, we keep its own C<CvOUTSIDE> for the time being, so that
1N/Athe chain of lexical scopes is unbroken. For example, the following
1N/A sub tmp { sub { eval '$x' } }
1N/A bool CvWEAKOUTSIDE(CV *cv)
1N/ASave the current pad in the given context block structure.
1N/A void CX_CURPAD_SAVE(struct context)
1N/AAccess the SV at offset po in the saved current pad in the given
1N/Acontext block structure (can be used as an lvalue).
1N/A SV * CX_CURPAD_SV(struct context, PADOFFSET po)
1N/AGet the value from slot C<po> in the base (DEPTH=1) pad of a padlist
1N/A SV * PAD_BASE_SV (PADLIST padlist, PADOFFSET po)
1N/AClone the state variables associated with running and compiling pads.
1N/A void PAD_CLONE_VARS(PerlInterpreter *proto_perl \)
1N/A=item PAD_COMPNAME_FLAGS
1N/AReturn the flags for the current compiling pad name
1N/Aat offset C<po>. Assumes a valid slot entry.
1N/A U32 PAD_COMPNAME_FLAGS(PADOFFSET po)
1N/A=item PAD_COMPNAME_GEN
1N/AThe generation number of the name at offset C<po> in the current
1N/Acompiling pad (lvalue). Note that C<SvCUR> is hijacked for this purpose.
1N/A STRLEN PAD_COMPNAME_GEN(PADOFFSET po)
1N/A=item PAD_COMPNAME_OURSTASH
1N/AReturn the stash associated with an C<our> variable.
1N/AAssumes the slot entry is a valid C<our> lexical.
1N/A HV * PAD_COMPNAME_OURSTASH(PADOFFSET po)
1N/A=item PAD_COMPNAME_PV
1N/AReturn the name of the current compiling pad name
1N/Aat offset C<po>. Assumes a valid slot entry.
1N/A char * PAD_COMPNAME_PV(PADOFFSET po)
1N/A=item PAD_COMPNAME_TYPE
1N/AReturn the type (stash) of the current compiling pad name at offset
1N/AC<po>. Must be a valid name. Returns null if not typed.
1N/A HV * PAD_COMPNAME_TYPE(PADOFFSET po)
1N/A void PAD_DUP(PADLIST dstpad, PADLIST srcpad, CLONE_PARAMS* param)
1N/A=item PAD_RESTORE_LOCAL
1N/ARestore the old pad saved into the local variable opad by PAD_SAVE_LOCAL()
1N/A void PAD_RESTORE_LOCAL(PAD *opad)
1N/ASave the current pad to the local variable opad, then make the
1N/Acurrent pad equal to npad
1N/A void PAD_SAVE_LOCAL(PAD *opad, PAD *npad)
1N/A=item PAD_SAVE_SETNULLPAD
1N/ASave the current pad then set it to null.
1N/A void PAD_SAVE_SETNULLPAD()
1N/ASet the slot at offset C<po> in the current pad to C<sv>
1N/A SV * PAD_SETSV (PADOFFSET po, SV* sv)
1N/ASet the current pad to be pad C<n> in the padlist, saving
1N/Athe previous current pad.
1N/A void PAD_SET_CUR (PADLIST padlist, I32 n)
1N/A=item PAD_SET_CUR_NOSAVE
1N/Alike PAD_SET_CUR, but without the save
1N/A void PAD_SET_CUR_NOSAVE (PADLIST padlist, I32 n)
1N/AGet the value at offset C<po> in the current pad
1N/A void PAD_SV (PADOFFSET po)
1N/ALightweight and lvalue version of C<PAD_SV>.
1N/AGet or set the value at offset C<po> in the current pad.
1N/AUnlike C<PAD_SV>, does not print diagnostics with -DX.
1N/AFor internal use only.
1N/A SV * PAD_SVl (PADOFFSET po)
1N/AClear the pointed to pad value on scope exit. (ie the runtime action of 'my')
1N/A void SAVECLEARSV (SV **svp)
1N/Asave PL_comppad and PL_curpad
1N/ASave a pad slot (used to restore after an iteration)
1N/AXXX DAPM it would make more sense to make the arg a PADOFFSET
1N/A void SAVEPADSV (PADOFFSET po)
1N/ALocate the CV corresponding to the currently executing sub or eval.
1N/AIf db_seqp is non_null, skip CVs that are in the DB package and populate
1N/A*db_seqp with the cop sequence number at the point that the DB:: code was
1N/Aentered. (allows debuggers to eval in the scope of the breakpoint rather
1N/Athan in in the scope of the debuger itself).
1N/A CV* find_runcv(U32 *db_seqp)
1N/A=head1 Global Variables
1N/AWhen Perl is run in debugging mode, with the B<-d> switch, this SV is a
1N/Aboolean which indicates whether subs are being single-stepped.
1N/ASingle-stepping is automatically turned on after every step. This is the C
1N/Avariable which corresponds to Perl's $DB::single variable. See
1N/AWhen Perl is run in debugging mode, with the B<-d> switch, this GV contains
1N/Athe SV which holds the name of the sub being debugged. This is the C
1N/Avariable which corresponds to Perl's $DB::sub variable. See
1N/ATrace variable used when Perl is run in debugging mode, with the B<-d>
1N/Aswitch. This is the C variable which corresponds to Perl's $DB::trace
1N/Avariable. See C<PL_DBsingle>.
1N/AThe C variable which corresponds to Perl's $^W warning variable.
1N/AThe GV which was last used for a filehandle input operation. (C<< <FH> >>)
1N/AThe output field separator - C<$,> in Perl space.
1N/AThe input record separator - C<$/> in Perl space.
1N/AReturns C<TRUE> if given the name of a magical GV.
1N/ACurrently only useful internally when determining if a GV should be
1N/Acreated even in rvalue contexts.
1N/AC<flags> is not used at present but available for future extension to
1N/Aallow selecting particular classes of magical variable.
1N/A bool is_gv_magical(char *name, STRLEN len, U32 flags)
1N/AFunction called by C<do_readline> to spawn a glob (or do the glob inside
1N/Aperl on VMS). This code used to be inline, but now perl uses C<File::Glob>
1N/Athis glob starter is only used by miniperl during the build process.
1N/A PerlIO* start_glob(SV* pattern, IO *io)
1N/A=head1 Pad Data Structures
1N/ACV's can have CvPADLIST(cv) set to point to an AV.
1N/AFor these purposes "forms" are a kind-of CV, eval""s are too (except they're
1N/Anot callable at will and are always thrown away after the eval"" is done
1N/AXSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad,
1N/Abut that is really the callers pad (a slot of which is allocated by
1N/AThe CvPADLIST AV has does not have AvREAL set, so REFCNT of component items
1N/Ais managed "manual" (mostly in
pad.c) rather than normal
av.c rules.
1N/AThe items in the AV are not SVs as for a normal AV, but other AVs:
1N/A0'th Entry of the CvPADLIST is an AV which represents the "names" or rather
1N/Athe "static type information" for lexicals.
1N/AThe CvDEPTH'th entry of CvPADLIST AV is an AV which is the stack frame at that
1N/Adepth of recursion into the CV.
1N/AThe 0'th slot of a frame AV is an AV which is @_.
1N/Aother entries are storage for variables and op targets.
1N/AC<PL_comppad_name> is set to the names AV.
1N/AC<PL_comppad> is set to the frame AV for the frame CvDEPTH == 1.
1N/AC<PL_curpad> is set to the body of the frame AV (
i.e. AvARRAY(PL_comppad)).
1N/ADuring execution, C<PL_comppad> and C<PL_curpad> refer to the live
1N/Aframe of the currently executing sub.
1N/AIterating over the names AV iterates over all possible pad
1N/A&PL_sv_undef "names" (see pad_alloc()).
1N/Aor resolved at compile time. These don't have names by which they
1N/Acan be looked up from Perl code at run time through eval"" like
1N/Amy/our variables can be. Since they can't be looked up by "name"
1N/Abut only by their index allocated at compile time (which is usually
1N/Ain PL_op->op_targ), wasting a name SV for them doesn't make sense.
1N/AThe SVs in the names AV have their PV being the name of the variable.
1N/ANV+
1..IV inclusive is a range of cop_seq numbers for which the name is
1N/Avalid. For typed lexicals name SV is SVt_PVMG and SvSTASH points at the
1N/Atype. For C<our> lexicals, the type is SVt_PVGV, and GvSTASH points at the
1N/Astash of the associated global (so that duplicate C<our> delarations in the
1N/Asame package can be detected). SvCUR is sometimes hijacked to
1N/Astore the generation number during compilation.
1N/AIf SvFAKE is set on the name SV then slot in the frame AVs are
1N/Aa REFCNT'ed references to a lexical from "outside". In this case,
1N/Athe name SV does not have a cop_seq range, since it is in scope
1N/AIf the 'name' is '&' the corresponding entry in frame AV
1N/Ais a CV representing a possible closure.
1N/A(SvFAKE and name of '&' is not a meaningful combination currently but could
1N/Abecome so if C<my sub foo {}> is implemented.)
1N/A AV * CvPADLIST(CV *cv)
1N/AClone a CV: make a new CV which points to the same code etc, but which
1N/Ahas a newly-created pad built by copying the prototype pad and capturing
1N/A CV* cv_clone(CV* proto)
1N/Adump the contents of a CV
1N/A void cv_dump(CV *cv, char *title)
1N/ADump the contents of a padlist
1N/A void do_dump_pad(I32 level, PerlIO *file, PADLIST *padlist, int full)
1N/A"Introduce" my variables to visible status.
1N/AAdd an anon code entry to the current compiling pad
1N/A PADOFFSET pad_add_anon(SV* sv, OPCODE op_type)
1N/ACreate a new name in the current pad at the specified offset.
1N/AIf C<typestash> is valid, the name is for a typed lexical; set the
1N/Aname's stash to that value.
1N/AIf C<ourstash> is valid, it's an our lexical, set the name's
1N/AGvSTASH to that value
1N/AAlso, if the name is @.. or %.., create a new array or hash for that slot
1N/AIf fake, it means we're cloning an existing entry
1N/A PADOFFSET pad_add_name(char *name, HV* typestash, HV* ourstash, bool clone)
1N/AAllocate a new my or tmp pad entry. For a my, simply push a null SV onto
1N/Athe end of PL_comppad, but for a tmp, scan the pad from PL_padix upwards
1N/Afor a slot which has no name and and no active value.
1N/A PADOFFSET pad_alloc(I32 optype, U32 tmptype)
1N/A=item pad_block_start
1N/AUpdate the pad compilation state variables on entry to a new block
1N/A void pad_block_start(int full)
1N/ACheck for duplicate declarations: report any of:
1N/A * a my in the current scope with the same name;
1N/A * an our (anywhere in the pad) with the same name and the same stash
1N/AC<is_our> indicates that the name to check is an 'our' declaration
1N/A void pad_check_dup(char* name, bool is_our, HV* ourstash)
1N/AFind a named lexical anywhere in a chain of nested pads. Add fake entries
1N/Ain the inner pads if it's found in an outer one. innercv is the CV *inside*
1N/Athe chain of outer CVs to be searched. If newoff is non-null, this is a
1N/Arun-time cloning: don't add fake entries, just find the lexical and add a
1N/Aref to it at newoff in the current pad.
1N/A PADOFFSET pad_findlex(char* name, PADOFFSET newoff, CV* innercv)
1N/AGiven a lexical name, try to find its offset, first in the current pad,
1N/Aor failing that, in the pads of any lexically enclosing subs (including
1N/Athe complications introduced by eval). If the name is found in an outer pad,
1N/Athen a fake entry is added to the current pad.
1N/AReturns the offset in the current pad, or NOT_IN_PAD on failure.
1N/A PADOFFSET pad_findmy(char* name)
1N/A=item pad_fixup_inner_anons
1N/AFor any anon CVs in the pad, change CvOUTSIDE of that CV from
1N/Aold_cv to new_cv if necessary. Needed when a newly-compiled CV has to be
1N/Amoved to a pre-existing CV struct.
1N/A void pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv, CV *new_cv)
1N/AFree the SV at offet po in the current pad.
1N/A void pad_free(PADOFFSET po)
1N/ACleanup at end of scope during compilation: set the max seq number for
1N/Alexicals in this scope and warn of any lexicals that never got introduced.
1N/ACreate a new compiling padlist, saving and updating the various global
1N/Avars at the same time as creating the pad itself. The following flags
1N/Acan be OR'ed together:
1N/A padnew_CLONE this pad is for a cloned CV
1N/A padnew_SAVE save old globals
1N/A padnew_SAVESUB also save extra stuff for start of sub
1N/A PADLIST* pad_new(int flags)
1N/APush a new pad frame onto the padlist, unless there's already a pad at
1N/Athis depth, in which case don't bother creating a new one.
1N/AIf has_args is true, give the new pad an @_ in slot zero.
1N/A void pad_push(PADLIST *padlist, int depth, int has_args)
1N/AMark all the current temporaries for reuse
1N/ASet the entry at offset po in the current pad to sv.
1N/AUse the macro PAD_SETSV() rather than calling this function directly.
1N/A void pad_setsv(PADOFFSET po, SV* sv)
1N/AAbandon the tmp in the current pad at offset po and replace with a
1N/A void pad_swipe(PADOFFSET po, bool refadjust)
1N/ATidy up a pad after we've finished compiling it:
1N/A * remove most stuff from the pads of anonsub prototypes;
1N/A * mark tmps as such.
1N/A void pad_tidy(padtidy_type type)
1N/AFree the padlist associated with a CV.
1N/AIf parts of it happen to be current, we null the relevant
1N/APL_*pad* global vars so that we don't have any dangling references left.
1N/AWe also repoint the CvOUTSIDE of any about-to-be-orphaned
1N/Ainner subs to the outer of this cv.
1N/A(This function should really be called pad_free, but the name was already
1N/A void pad_undef(CV* cv)
1N/A=head1 Stack Manipulation Macros
1N/ADeclare Just C<SP>. This is actually identical to C<dSP>, and declares
1N/Aa local copy of perl's stack pointer, available via the C<SP> macro.
1N/ASee C<SP>. (Available for backward source code compatibility with the
1N/Aold (Perl 5.005) thread model.)
1N/ATrue if this op will be the return value of an lvalue subroutine
1N/A=head1 SV Manipulation Functions
1N/APrint appropriate "Use of uninitialized variable" warning
1N/A void report_uninit()
1N/AGiven a chunk of memory, link it to the head of the list of arenas,
1N/Aand split it into a list of free SVs.
1N/A void sv_add_arena(char* ptr, U32 size, U32 flags)
1N/ADecrement the refcnt of each remaining SV, possibly triggering a
1N/Acleanup. This function may have to be called multiple times to free
1N/ASVs which are in complex self-referential hierarchies.
1N/AAttempt to destroy all objects not yet freed
1N/A void sv_clean_objs()
1N/ADeallocate the memory used by all arenas. Note that all the individual SV
1N/Aheads and bodies within the arenas must already have been freed.
1N/A void sv_free_arenas()
1N/AThe autodocumentation system was originally added to the Perl core by
1N/ABenjamin Stuhl. Documentation is by whoever was kind enough to
1N/Adocument their functions.
1N/Aperlguts(1), perlapi(1)