From a4f1a0295dfc0733a51ca0623d486d082d04773a Mon Sep 17 00:00:00 2001 From: Nick Ing-Simmons Date: Fri, 8 Feb 2002 09:19:29 +0000 Subject: [PATCH] Extract something from yesterdays effort - convert my mail on pad data structures (incoporating Sarathy's corrections/clarifications) into POD in cv.h which gets autodoc.pl'ed into pod/perlintern.pod. p4raw-id: //depot/perlio@14595 --- cv.h | 59 ++++++++++++++ pod/perlapi.pod | 222 +++++++++++++++++++++++++++++------------------------ pod/perlintern.pod | 171 ++++++++++++++++++++++++++++++++--------- 3 files changed, 315 insertions(+), 137 deletions(-) diff --git a/cv.h b/cv.h index 2c438be..824517c 100644 --- a/cv.h +++ b/cv.h @@ -136,3 +136,62 @@ Returns the stash of the CV. #define CvCONST(cv) (CvFLAGS(cv) & CVf_CONST) #define CvCONST_on(cv) (CvFLAGS(cv) |= CVf_CONST) #define CvCONST_off(cv) (CvFLAGS(cv) &= ~CVf_CONST) + +/* +=head1 Pad Data Structures + +=for apidoc m|AV *|CvPADLIST|CV *cv +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). + +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 op.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 the the the names AV. +C is set the the frame AV for the frame CvDEPTH == 1. +C is set the body of the frame AV (i.e. AvARRAY(PL_comppad)). + +Itterating over the names AV itterates 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. + +If SvFAKE is set on the name SV then slot in the frame AVs are +a REFCNT'ed references to a lexical from "outside". + +If the 'name' is '&' the 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.) + +=cut +*/ + diff --git a/pod/perlapi.pod b/pod/perlapi.pod index d55b88a..dc52664 100644 --- a/pod/perlapi.pod +++ b/pod/perlapi.pod @@ -1266,6 +1266,16 @@ argument more than once. =for hackers Found in file sv.h +=item SvLOCK + +Arranges for a mutual exclusion lock to be obtained on sv if a suitable module +has been loaded. + + void SvLOCK(SV* sv) + +=for hackers +Found in file sv.h + =item SvSETMAGIC Invokes C on an SV if it has 'set' magic. This macro evaluates its @@ -1285,6 +1295,15 @@ Like C, but does any set magic required afterwards. =for hackers Found in file sv.h +=item SvSetMagicSV_nosteal + +Like C, but does any set magic required afterwards. + + void SvSetMagicSV_nosteal(SV* dsv, SV* ssv) + +=for hackers +Found in file sv.h + =item SvSetSV Calls C if dsv is not the same as ssv. May evaluate arguments @@ -1305,6 +1324,16 @@ ssv. May evaluate arguments more than once. =for hackers Found in file sv.h +=item SvSHARE + +Arranges for sv to be shared between threads if a suitable module +has been loaded. + + void SvSHARE(SV* sv) + +=for hackers +Found in file sv.h + =back @@ -1417,13 +1446,24 @@ Found in file util.c =item savepvn Copy a string to a safe spot. The C indicates number of bytes to -copy. This does not use an SV. +copy. If pointer is NULL allocate space for a string of size specified. +This does not use an SV. char* savepvn(const char* sv, I32 len) =for hackers Found in file util.c +=item savesharedpv + +Copy a string to a safe spot in memory shared between threads. +This does not use an SV. + + char* savesharedpv(const char* sv) + +=for hackers +Found in file util.c + =item StructCopy This is an architecture-independent macro to copy one structure to another. @@ -1750,77 +1790,6 @@ Found in file op.c =back -=head1 Shared SV Functions - -=over 8 - -=item sharedsv_find - -Tries to find if a given SV has a shared backend, either by -looking at magic, or by checking if it is tied again threads::shared. - - shared_sv* sharedsv_find(SV* sv) - -=for hackers -Found in file sharedsv.c - -=item sharedsv_init - -Saves a space for keeping SVs wider than an interpreter, -currently only stores a pointer to the first interpreter. - - void sharedsv_init() - -=for hackers -Found in file sharedsv.c - -=item sharedsv_lock - -Recursive locks on a sharedsv. -Locks are dynamically scoped at the level of the first lock. - void sharedsv_lock(shared_sv* ssv) - -=for hackers -Found in file sharedsv.c - -=item sharedsv_new - -Allocates a new shared sv struct, you must yourself create the SV/AV/HV. - shared_sv* sharedsv_new() - -=for hackers -Found in file sharedsv.c - -=item sharedsv_thrcnt_dec - -Decrements the threadcount of a shared sv. When a threads frontend is freed -this function should be called. - - void sharedsv_thrcnt_dec(shared_sv* ssv) - -=for hackers -Found in file sharedsv.c - -=item sharedsv_thrcnt_inc - -Increments the threadcount of a sharedsv. - void sharedsv_thrcnt_inc(shared_sv* ssv) - -=for hackers -Found in file sharedsv.c - -=item sharedsv_unlock - -Recursively unlocks a shared sv. - - void sharedsv_unlock(shared_sv* ssv) - -=for hackers -Found in file sharedsv.c - - -=back - =head1 Stack Manipulation Macros =over 8 @@ -2899,21 +2868,21 @@ Like C, but converts sv to utf8 first if necessary. =for hackers Found in file sv.h -=item SvPVX +=item SvPVx -Returns a pointer to the physical string in the SV. The SV must contain a -string. +A version of C which guarantees to evaluate sv only once. - char* SvPVX(SV* sv) + char* SvPVx(SV* sv, STRLEN len) =for hackers Found in file sv.h -=item SvPVx +=item SvPVX -A version of C which guarantees to evaluate sv only once. +Returns a pointer to the physical string in the SV. The SV must contain a +string. - char* SvPVx(SV* sv, STRLEN len) + char* SvPVX(SV* sv) =for hackers Found in file sv.h @@ -3011,16 +2980,6 @@ Dereferences an RV to return the SV. =for hackers Found in file sv.h -=item SvSetMagicSV_nosteal - -Like C, but does any set magic required afterwards. - - - void SvSetMagicSV_nosteal(SV* dsv, SV* ssv) - -=for hackers -Found in file sv.h - =item SvSTASH Returns the stash of the SV. @@ -3091,6 +3050,17 @@ Returns the type of the SV. See C. =for hackers Found in file sv.h +=item SvUNLOCK + +Releases a mutual exclusion lock on sv if a suitable module +has been loaded. + + + void SvUNLOCK(SV* sv) + +=for hackers +Found in file sv.h + =item SvUOK Returns a boolean indicating whether the SV contains an unsigned integer. @@ -3148,22 +3118,22 @@ for a version which guarantees to evaluate sv only once. =for hackers Found in file sv.h -=item SvUVx +=item SvUVX -Coerces the given SV to an unsigned integer and returns it. Guarantees to -evaluate sv only once. Use the more efficient C otherwise. +Returns the raw value in the SV's UV slot, without checks or conversions. +Only use when you are sure SvIOK is true. See also C. - UV SvUVx(SV* sv) + UV SvUVX(SV* sv) =for hackers Found in file sv.h -=item SvUVX +=item SvUVx -Returns the raw value in the SV's UV slot, without checks or conversions. -Only use when you are sure SvIOK is true. See also C. +Coerces the given SV to an unsigned integer and returns it. Guarantees to +evaluate sv only once. Use the more efficient C otherwise. - UV SvUVX(SV* sv) + UV SvUVx(SV* sv) =for hackers Found in file sv.h @@ -3674,13 +3644,32 @@ Found in file sv.c Adds magic to an SV. First upgrades C to type C if necessary, then adds a new magic item of type C to the head of the magic list. -C is assumed to contain an C if C<(name && namelen == HEf_SVKEY)> - void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen) =for hackers Found in file sv.c +=item sv_magicext + +Adds magic to an SV, upgrading it if necessary. Applies the +supplied vtable and returns pointer to the magic added. + +Note that sv_magicext will allow things that sv_magic will not. +In particular you can add magic to SvREADONLY SVs and and more than +one instance of the same 'how' + +I C is greater then zero then a savepvn() I of C is stored, +if C is zero then C is stored as-is and - as another special +case - if C<(name && namelen == HEf_SVKEY)> then C is assumed to contain +an C and has its REFCNT incremented + +(This is now used as a subroutine by sv_magic.) + + MAGIC * sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen ) + +=for hackers +Found in file sv.c + =item sv_mortalcopy Creates a new SV which is a copy of the original SV (using C). @@ -3715,6 +3704,39 @@ instead. =for hackers Found in file sv.c +=item sv_nolocking + +Dummy routine which "locks" an SV when there is no locking module present. +Exists to avoid test for a NULL function pointer and because it could potentially warn under +some level of strict-ness. + + void sv_nolocking(SV *) + +=for hackers +Found in file util.c + +=item sv_nosharing + +Dummy routine which "shares" an SV when there is no sharing module present. +Exists to avoid test for a NULL function pointer and because it could potentially warn under +some level of strict-ness. + + void sv_nosharing(SV *) + +=for hackers +Found in file util.c + +=item sv_nounlocking + +Dummy routine which "unlocks" an SV when there is no locking module present. +Exists to avoid test for a NULL function pointer and because it could potentially warn under +some level of strict-ness. + + void sv_nounlocking(SV *) + +=for hackers +Found in file util.c + =item sv_nv A private implementation of the C macro for compilers which can't @@ -4477,7 +4499,7 @@ length len, the displayable version being at most pvlim bytes long (if longer, the rest is truncated and "..." will be appended). The flags argument can have UNI_DISPLAY_ISPRINT set to display -isprint()able characters as themselves, UNI_DISPLAY_BACKSLASH +isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH to display the \\[nrfta\\] as the backslashed versions (like '\n') (UNI_DISPLAY_BACKSLASH is preferred over UNI_DISPLAY_ISPRINT for \\). UNI_DISPLAY_QQ (and its alias UNI_DISPLAY_REGEX) have both diff --git a/pod/perlintern.pod b/pod/perlintern.pod index 544b878..c9cb5e7 100644 --- a/pod/perlintern.pod +++ b/pod/perlintern.pod @@ -10,41 +10,10 @@ 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! -=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 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 gv.c - -=item LVRET - -True if this op will be the return value of an lvalue subroutine +=head1 Global Variables -=for hackers -Found in file pp.h +=over 8 =item PL_DBsingle @@ -118,14 +87,34 @@ 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 - void report_uninit() +=head1 GV Functions + +=over 8 + +=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 @@ -139,6 +128,113 @@ 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). + +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 op.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 the the the names AV. +C is set the the frame AV for the frame CvDEPTH == 1. +C is set the body of the frame AV (i.e. AvARRAY(PL_comppad)). + +Itterating over the names AV itterates 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. + +If SvFAKE is set on the name SV then slot in the frame AVs are +a REFCNT'ed references to a lexical from "outside". + +If the 'name' is '&' the 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.) + + AV * CvPADLIST(CV *cv) + +=for hackers +Found in file cv.h + + +=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 report_uninit + +Print appropriate "Use of uninitialized variable" warning + + void report_uninit() + +=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, @@ -179,6 +275,7 @@ heads and bodies within the arenas must already have been freed. =for hackers Found in file sv.c + =back =head1 AUTHORS -- 1.8.3.1