X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlintern.pod;h=50f3d51af949f34b3e9115ef951b818086c9d2f7;hb=8a2485f87de4ac33d6c8564ae6b27c5efc3e1430;hp=a0cf47c0497db849fc36928c4709cae600d7eff8;hpb=645c22eff49f10f8bfaa5864a990561e60fea631;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlintern.pod b/pod/perlintern.pod index a0cf47c..50f3d51 100644 --- a/pod/perlintern.pod +++ b/pod/perlintern.pod @@ -10,41 +10,306 @@ Perl interpreter that are documented using Perl's internal documentation format but are not marked as part of the Perl API. In other words, B! + +=head1 CV reference counts and CvOUTSIDE + =over 8 -=item djSP +=item CvWEAKOUTSIDE + +Each CV has a pointer, C, to its lexically enclosing +CV (if any). Because pointers to anonymous sub prototypes are +stored in C<&> pad slots, it is a possible to get a circular reference, +with the parent pointing to the child and vice-versa. To avoid the +ensuing memory leak, we do not increment the reference count of the CV +pointed to by C in the I that the parent +has a C<&> pad slot pointing back to us. In this case, we set the +C flag in the child. This allows us to determine under what +circumstances we should decrement the refcount of the parent when freeing +the child. + +There is a further complication with non-closure anonymous subs (ie those +that do not refer to any lexicals outside that sub). In this case, the +anonymous prototype is shared rather than being cloned. This has the +consequence that the parent may be freed while there are still active +children, eg + + BEGIN { $a = sub { eval '$x' } } + +In this case, the BEGIN is freed immediately after execution since there +are no active references to it: the anon sub prototype has +C set since it's not a closure, and $a points to the same +CV, so it doesn't contribute to BEGIN's refcount either. When $a is +executed, the C causes the chain of Cs to be followed, +and the freed BEGIN is accessed. + +To avoid this, whenever a CV and its associated pad is freed, any +C<&> entries in the pad are explicitly removed from the pad, and if the +refcount of the pointed-to anon sub is still positive, then that +child's C is set to point to its grandparent. This will only +occur in the single specific case of a non-closure anon prototype +having one or more active references (such as C<$a> above). + +One other thing to consider is that a CV may be merely undefined +rather than freed, eg C. In this case, its refcount may +not have reached zero, but we still delete its pad and its C etc. +Since various children may still have their C pointing at this +undefined CV, we keep its own C for the time being, so that +the chain of lexical scopes is unbroken. For example, the following +should print 123: + + my $x = 123; + sub tmp { sub { eval '$x' } } + my $a = tmp(); + undef &tmp; + print $a->(); + + bool CvWEAKOUTSIDE(CV *cv) -Declare Just C. This is actually identical to C, and declares -a local copy of perl's stack pointer, available via the C macro. -See C. (Available for backward source code compatibility with the -old (Perl 5.005) thread model.) +=for hackers +Found in file cv.h - djSP; + +=back + +=head1 Functions in file pad.h + + +=over 8 + +=item CX_CURPAD_SAVE + +Save the current pad in the given context block structure. + + void CX_CURPAD_SAVE(struct context) =for hackers -Found in file pp.h +Found in file pad.h -=item is_gv_magical +=item CX_CURPAD_SV -Returns C if given the name of a magical GV. +Access the SV at offset po in the saved current pad in the given +context block structure (can be used as an lvalue). -Currently only useful internally when determining if a GV should be -created even in rvalue contexts. + SV * CX_CURPAD_SV(struct context, PADOFFSET po) -C is not used at present but available for future extension to -allow selecting particular classes of magical variable. +=for hackers +Found in file pad.h - bool is_gv_magical(char *name, STRLEN len, U32 flags) +=item PAD_BASE_SV + +Get the value from slot C in the base (DEPTH=1) pad of a padlist + + SV * PAD_BASE_SV (PADLIST padlist, PADOFFSET po) =for hackers -Found in file gv.c +Found in file pad.h -=item LVRET +=item PAD_CLONE_VARS -True if this op will be the return value of an lvalue subroutine +|CLONE_PARAMS* param +Clone the state variables associated with running and compiling pads. + + void PAD_CLONE_VARS(PerlInterpreter *proto_perl \) =for hackers -Found in file pp.h +Found in file pad.h + +=item PAD_COMPNAME_FLAGS + +Return the flags for the current compiling pad name +at offset C. Assumes a valid slot entry. + + U32 PAD_COMPNAME_FLAGS(PADOFFSET po) + +=for hackers +Found in file pad.h + +=item PAD_COMPNAME_GEN + +The generation number of the name at offset C in the current +compiling pad (lvalue). Note that C is hijacked for this purpose. + + STRLEN PAD_COMPNAME_GEN(PADOFFSET po) + +=for hackers +Found in file pad.h + +=item PAD_COMPNAME_OURSTASH + +Return the stash associated with an C variable. +Assumes the slot entry is a valid C lexical. + + HV * PAD_COMPNAME_OURSTASH(PADOFFSET po) + +=for hackers +Found in file pad.h + +=item PAD_COMPNAME_PV + +Return the name of the current compiling pad name +at offset C. Assumes a valid slot entry. + + char * PAD_COMPNAME_PV(PADOFFSET po) + +=for hackers +Found in file pad.h + +=item PAD_COMPNAME_TYPE + +Return the type (stash) of the current compiling pad name at offset +C. Must be a valid name. Returns null if not typed. + + HV * PAD_COMPNAME_TYPE(PADOFFSET po) + +=for hackers +Found in file pad.h + +=item PAD_DUP + +Clone a padlist. + + void PAD_DUP(PADLIST dstpad, PADLIST srcpad, CLONE_PARAMS* param) + +=for hackers +Found in file pad.h + +=item PAD_RESTORE_LOCAL + +Restore the old pad saved into the local variable opad by PAD_SAVE_LOCAL() + + void PAD_RESTORE_LOCAL(PAD *opad) + +=for hackers +Found in file pad.h + +=item PAD_SAVE_LOCAL + +Save the current pad to the local variable opad, then make the +current pad equal to npad + + void PAD_SAVE_LOCAL(PAD *opad, PAD *npad) + +=for hackers +Found in file pad.h + +=item PAD_SAVE_SETNULLPAD + +Save the current pad then set it to null. + + void PAD_SAVE_SETNULLPAD() + +=for hackers +Found in file pad.h + +=item PAD_SETSV + +Set the slot at offset C in the current pad to C + + SV * PAD_SETSV (PADOFFSET po, SV* sv) + +=for hackers +Found in file pad.h + +=item PAD_SET_CUR + +Set the current pad to be pad C in the padlist, saving +the previous current pad. + + void PAD_SET_CUR (PADLIST padlist, I32 n) + +=for hackers +Found in file pad.h + +=item PAD_SET_CUR_NOSAVE + +like PAD_SET_CUR, but without the save + + void PAD_SET_CUR_NOSAVE (PADLIST padlist, I32 n) + +=for hackers +Found in file pad.h + +=item PAD_SV + +Get the value at offset C in the current pad + + void PAD_SV (PADOFFSET po) + +=for hackers +Found in file pad.h + +=item PAD_SVl + +Lightweight and lvalue version of C. +Get or set the value at offset C in the current pad. +Unlike C, does not print diagnostics with -DX. +For internal use only. + + SV * PAD_SVl (PADOFFSET po) + +=for hackers +Found in file pad.h + +=item SAVECLEARSV + +Clear the pointed to pad value on scope exit. (ie the runtime action of 'my') + + void SAVECLEARSV (SV **svp) + +=for hackers +Found in file pad.h + +=item SAVECOMPPAD + +save PL_comppad and PL_curpad + + + + + + void SAVECOMPPAD() + +=for hackers +Found in file pad.h + +=item SAVEPADSV + +Save a pad slot (used to restore after an iteration) + +XXX DAPM it would make more sense to make the arg a PADOFFSET + void SAVEPADSV (PADOFFSET po) + +=for hackers +Found in file pad.h + + +=back + +=head1 Functions in file pp_ctl.c + + +=over 8 + +=item find_runcv + +Locate the CV corresponding to the currently executing sub or eval. +If db_seqp is non_null, skip CVs that are in the DB package and populate +*db_seqp with the cop sequence number at the point that the DB:: code was +entered. (allows debuggers to eval in the scope of the breakpoint rather +than in in the scope of the debugger itself). + + CV* find_runcv(U32 *db_seqp) + +=for hackers +Found in file pp_ctl.c + + +=back + +=head1 Global Variables + +=over 8 =item PL_DBsingle @@ -118,20 +383,40 @@ The input record separator - C<$/> in Perl space. =for hackers Found in file thrdvar.h -=item report_uninit -Print appropriate "Use of uninitialized variable" warning +=back + +=head1 GV Functions + +=over 8 - void report_uninit() +=item is_gv_magical + +Returns C if given the name of a magical GV. + +Currently only useful internally when determining if a GV should be +created even in rvalue contexts. + +C is not used at present but available for future extension to +allow selecting particular classes of magical variable. + + bool is_gv_magical(char *name, STRLEN len, U32 flags) =for hackers -Found in file sv.c +Found in file gv.c + + +=back + +=head1 IO Functions + +=over 8 =item start_glob Function called by C to spawn a glob (or do the glob inside perl on VMS). This code used to be inline, but now perl uses C -this glob starter is only used by miniperl during the build proccess. +this glob starter is only used by miniperl during the build process. Moving it away shrinks pp_hot.c; shrinking pp_hot.c helps speed perl up. PerlIO* start_glob(SV* pattern, IO *io) @@ -139,6 +424,403 @@ Moving it away shrinks pp_hot.c; shrinking pp_hot.c helps speed perl up. =for hackers Found in file doio.c + +=back + +=head1 Pad Data Structures + +=over 8 + +=item CvPADLIST + +CV's can have CvPADLIST(cv) set to point to an AV. + +For these purposes "forms" are a kind-of CV, eval""s are too (except they're +not callable at will and are always thrown away after the eval"" is done +executing). Require'd files are simply evals without any outer lexical +scope. + +XSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad, +but that is really the callers pad (a slot of which is allocated by +every entersub). + +The CvPADLIST AV has does not have AvREAL set, so REFCNT of component items +is managed "manual" (mostly in pad.c) rather than normal av.c rules. +The items in the AV are not SVs as for a normal AV, but other AVs: + +0'th Entry of the CvPADLIST is an AV which represents the "names" or rather +the "static type information" for lexicals. + +The CvDEPTH'th entry of CvPADLIST AV is an AV which is the stack frame at that +depth of recursion into the CV. +The 0'th slot of a frame AV is an AV which is @_. +other entries are storage for variables and op targets. + +During compilation: +C is set to the names AV. +C is set to the frame AV for the frame CvDEPTH == 1. +C is set to the body of the frame AV (i.e. AvARRAY(PL_comppad)). + +During execution, C and C refer to the live +frame of the currently executing sub. + +Iterating over the names AV iterates over all possible pad +items. Pad slots that are SVs_PADTMP (targets/GVs/constants) end up having +&PL_sv_undef "names" (see pad_alloc()). + +Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid names. +The rest are op targets/GVs/constants which are statically allocated +or resolved at compile time. These don't have names by which they +can be looked up from Perl code at run time through eval"" like +my/our variables can be. Since they can't be looked up by "name" +but only by their index allocated at compile time (which is usually +in PL_op->op_targ), wasting a name SV for them doesn't make sense. + +The SVs in the names AV have their PV being the name of the variable. +NV+1..IV inclusive is a range of cop_seq numbers for which the name is +valid. For typed lexicals name SV is SVt_PVMG and SvSTASH points at the +type. For C lexicals, the type is SVt_PVGV, and GvSTASH points at the +stash of the associated global (so that duplicate C delarations in the +same package can be detected). SvCUR is sometimes hijacked to +store the generation number during compilation. + +If SvFAKE is set on the name SV, then that slot in the frame AV is +a REFCNT'ed reference to a lexical from "outside". In this case, +the name SV does not use NVX and IVX to store a cop_seq range, since it is +in scope throughout. Instead IVX stores some flags containing info about +the real lexical (is it declared in an anon, and is it capable of being +instantiated multiple times?), and for fake ANONs, NVX contains the index +within the parent's pad where the lexical's value is stored, to make +cloning quicker. + +If the 'name' is '&' the corresponding entry in frame AV +is a CV representing a possible closure. +(SvFAKE and name of '&' is not a meaningful combination currently but could +become so if C is implemented.) + +Note that formats are treated as anon subs, and are cloned each time +write is called (if necessary). + +The flag SVf_PADSTALE is cleared on lexicals each time the my() is executed, +and set on scope exit. This allows the 'Variable $x is not available' warning +to be generated in evals, such as + + { my $x = 1; sub f { eval '$x'} } f(); + + AV * CvPADLIST(CV *cv) + +=for hackers +Found in file pad.c + +=item cv_clone + +Clone a CV: make a new CV which points to the same code etc, but which +has a newly-created pad built by copying the prototype pad and capturing +any outer lexicals. + + CV* cv_clone(CV* proto) + +=for hackers +Found in file pad.c + +=item cv_dump + +dump the contents of a CV + + void cv_dump(CV *cv, char *title) + +=for hackers +Found in file pad.c + +=item do_dump_pad + +Dump the contents of a padlist + + void do_dump_pad(I32 level, PerlIO *file, PADLIST *padlist, int full) + +=for hackers +Found in file pad.c + +=item intro_my + +"Introduce" my variables to visible status. + + U32 intro_my() + +=for hackers +Found in file pad.c + +=item pad_add_anon + +Add an anon code entry to the current compiling pad + + PADOFFSET pad_add_anon(SV* sv, OPCODE op_type) + +=for hackers +Found in file pad.c + +=item pad_add_name + +Create a new name and associated PADMY SV in the current pad; return the +offset. +If C is valid, the name is for a typed lexical; set the +name's stash to that value. +If C is valid, it's an our lexical, set the name's +GvSTASH to that value + +If fake, it means we're cloning an existing entry + + PADOFFSET pad_add_name(char *name, HV* typestash, HV* ourstash, bool clone) + +=for hackers +Found in file pad.c + +=item pad_alloc + +Allocate a new my or tmp pad entry. For a my, simply push a null SV onto +the end of PL_comppad, but for a tmp, scan the pad from PL_padix upwards +for a slot which has no name and and no active value. + + PADOFFSET pad_alloc(I32 optype, U32 tmptype) + +=for hackers +Found in file pad.c + +=item pad_block_start + +Update the pad compilation state variables on entry to a new block + + void pad_block_start(int full) + +=for hackers +Found in file pad.c + +=item pad_check_dup + +Check for duplicate declarations: report any of: + * a my in the current scope with the same name; + * an our (anywhere in the pad) with the same name and the same stash + as C +C indicates that the name to check is an 'our' declaration + + void pad_check_dup(char* name, bool is_our, HV* ourstash) + +=for hackers +Found in file pad.c + +=item pad_findlex + +Find a named lexical anywhere in a chain of nested pads. Add fake entries +in the inner pads if it's found in an outer one. + +Returns the offset in the bottom pad of the lex or the fake lex. +cv is the CV in which to start the search, and seq is the current cop_seq +to match against. If warn is true, print appropriate warnings. The out_* +vars return values, and so are pointers to where the returned values +should be stored. out_capture, if non-null, requests that the innermost +instance of the lexical is captured; out_name_sv is set to the innermost +matched namesv or fake namesv; out_flags returns the flags normally +associated with the IVX field of a fake namesv. + +Note that pad_findlex() is recursive; it recurses up the chain of CVs, +then comes back down, adding fake entries as it goes. It has to be this way +because fake namesvs in anon protoypes have to store in NVX the index into +the parent pad. + + PADOFFSET pad_findlex(char *name, CV* cv, U32 seq, int warn, SV** out_capture, SV** out_name_sv, int *out_flags) + +=for hackers +Found in file pad.c + +=item pad_findmy + +Given a lexical name, try to find its offset, first in the current pad, +or failing that, in the pads of any lexically enclosing subs (including +the complications introduced by eval). If the name is found in an outer pad, +then a fake entry is added to the current pad. +Returns the offset in the current pad, or NOT_IN_PAD on failure. + + PADOFFSET pad_findmy(char* name) + +=for hackers +Found in file pad.c + +=item pad_fixup_inner_anons + +For any anon CVs in the pad, change CvOUTSIDE of that CV from +old_cv to new_cv if necessary. Needed when a newly-compiled CV has to be +moved to a pre-existing CV struct. + + void pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv, CV *new_cv) + +=for hackers +Found in file pad.c + +=item pad_free + +Free the SV at offet po in the current pad. + + void pad_free(PADOFFSET po) + +=for hackers +Found in file pad.c + +=item pad_leavemy + +Cleanup at end of scope during compilation: set the max seq number for +lexicals in this scope and warn of any lexicals that never got introduced. + + void pad_leavemy() + +=for hackers +Found in file pad.c + +=item pad_new + +Create a new compiling padlist, saving and updating the various global +vars at the same time as creating the pad itself. The following flags +can be OR'ed together: + + padnew_CLONE this pad is for a cloned CV + padnew_SAVE save old globals + padnew_SAVESUB also save extra stuff for start of sub + + PADLIST* pad_new(int flags) + +=for hackers +Found in file pad.c + +=item pad_push + +Push a new pad frame onto the padlist, unless there's already a pad at +this depth, in which case don't bother creating a new one. +If has_args is true, give the new pad an @_ in slot zero. + + void pad_push(PADLIST *padlist, int depth, int has_args) + +=for hackers +Found in file pad.c + +=item pad_reset + +Mark all the current temporaries for reuse + + void pad_reset() + +=for hackers +Found in file pad.c + +=item pad_setsv + +Set the entry at offset po in the current pad to sv. +Use the macro PAD_SETSV() rather than calling this function directly. + + void pad_setsv(PADOFFSET po, SV* sv) + +=for hackers +Found in file pad.c + +=item pad_swipe + +Abandon the tmp in the current pad at offset po and replace with a +new one. + + void pad_swipe(PADOFFSET po, bool refadjust) + +=for hackers +Found in file pad.c + +=item pad_tidy + +Tidy up a pad after we've finished compiling it: + * remove most stuff from the pads of anonsub prototypes; + * give it a @_; + * mark tmps as such. + + void pad_tidy(padtidy_type type) + +=for hackers +Found in file pad.c + +=item pad_undef + +Free the padlist associated with a CV. +If parts of it happen to be current, we null the relevant +PL_*pad* global vars so that we don't have any dangling references left. +We also repoint the CvOUTSIDE of any about-to-be-orphaned +inner subs to the outer of this cv. + +(This function should really be called pad_free, but the name was already +taken) + + void pad_undef(CV* cv) + +=for hackers +Found in file pad.c + + +=back + +=head1 Stack Manipulation Macros + +=over 8 + +=item djSP + +Declare Just C. This is actually identical to C, and declares +a local copy of perl's stack pointer, available via the C macro. +See C. (Available for backward source code compatibility with the +old (Perl 5.005) thread model.) + + djSP; + +=for hackers +Found in file pp.h + +=item LVRET + +True if this op will be the return value of an lvalue subroutine + +=for hackers +Found in file pp.h + + +=back + +=head1 SV Manipulation Functions + +=over 8 + +=item find_uninit_var + +Find the name of the undefined variable (if any) that caused the operator o +to issue a "Use of uninitialized value" warning. +If match is true, only return a name if it's value matches uninit_sv. +So roughly speaking, if a unary operator (such as OP_COS) generates a +warning, then following the direct child of the op may yield an +OP_PADSV or OP_GV that gives the name of the undefined variable. On the +other hand, with OP_ADD there are two branches to follow, so we only print +the variable name if we get an exact match. + +The name is returned as a mortal SV. + +Assumes that PL_op is the op that originally triggered the error, and that +PL_comppad/PL_curpad points to the currently executing pad. + + SV* find_uninit_var(OP* obase, SV* uninit_sv, bool top) + +=for hackers +Found in file sv.c + +=item report_uninit + +Print appropriate "Use of uninitialized variable" warning + + void report_uninit(SV* uninit_sv) + +=for hackers +Found in file sv.c + =item sv_add_arena Given a chunk of memory, link it to the head of the list of arenas, @@ -153,7 +835,7 @@ Found in file sv.c Decrement the refcnt of each remaining SV, possibly triggering a cleanup. This function may have to be called multiple times to free -SVs which are in complex self-referential heirarchies. +SVs which are in complex self-referential hierarchies. I32 sv_clean_all() @@ -179,6 +861,7 @@ heads and bodies within the arenas must already have been freed. =for hackers Found in file sv.c + =back =head1 AUTHORS