1*0Sstevel@tonic-gate /* cv.h 2*0Sstevel@tonic-gate * 3*0Sstevel@tonic-gate * Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1999, 4*0Sstevel@tonic-gate * 2000, 2001, 2002, 2003, 2004, by Larry Wall and others 5*0Sstevel@tonic-gate * 6*0Sstevel@tonic-gate * You may distribute under the terms of either the GNU General Public 7*0Sstevel@tonic-gate * License or the Artistic License, as specified in the README file. 8*0Sstevel@tonic-gate * 9*0Sstevel@tonic-gate */ 10*0Sstevel@tonic-gate 11*0Sstevel@tonic-gate /* This structure must match XPVCV in B/C.pm and the beginning of XPVFM 12*0Sstevel@tonic-gate * in sv.h */ 13*0Sstevel@tonic-gate 14*0Sstevel@tonic-gate struct xpvcv { 15*0Sstevel@tonic-gate char * xpv_pv; /* pointer to malloced string (for prototype) */ 16*0Sstevel@tonic-gate STRLEN xpv_cur; /* length of xp_pv as a C string */ 17*0Sstevel@tonic-gate STRLEN xpv_len; /* allocated size */ 18*0Sstevel@tonic-gate IV xof_off; /* integer value */ 19*0Sstevel@tonic-gate NV xnv_nv; /* numeric value, if any */ 20*0Sstevel@tonic-gate MAGIC* xmg_magic; /* magic for scalar array */ 21*0Sstevel@tonic-gate HV* xmg_stash; /* class package */ 22*0Sstevel@tonic-gate 23*0Sstevel@tonic-gate HV * xcv_stash; 24*0Sstevel@tonic-gate OP * xcv_start; 25*0Sstevel@tonic-gate OP * xcv_root; 26*0Sstevel@tonic-gate void (*xcv_xsub) (pTHX_ CV*); 27*0Sstevel@tonic-gate ANY xcv_xsubany; 28*0Sstevel@tonic-gate GV * xcv_gv; 29*0Sstevel@tonic-gate char * xcv_file; 30*0Sstevel@tonic-gate long xcv_depth; /* >= 2 indicates recursive call */ 31*0Sstevel@tonic-gate PADLIST * xcv_padlist; 32*0Sstevel@tonic-gate CV * xcv_outside; 33*0Sstevel@tonic-gate #ifdef USE_5005THREADS 34*0Sstevel@tonic-gate perl_mutex *xcv_mutexp; 35*0Sstevel@tonic-gate struct perl_thread *xcv_owner; /* current owner thread */ 36*0Sstevel@tonic-gate #endif /* USE_5005THREADS */ 37*0Sstevel@tonic-gate cv_flags_t xcv_flags; 38*0Sstevel@tonic-gate U32 xcv_outside_seq; /* the COP sequence (at the point of our 39*0Sstevel@tonic-gate * compilation) in the lexically enclosing 40*0Sstevel@tonic-gate * sub */ 41*0Sstevel@tonic-gate }; 42*0Sstevel@tonic-gate 43*0Sstevel@tonic-gate /* 44*0Sstevel@tonic-gate =head1 Handy Values 45*0Sstevel@tonic-gate 46*0Sstevel@tonic-gate =for apidoc AmU||Nullcv 47*0Sstevel@tonic-gate Null CV pointer. 48*0Sstevel@tonic-gate 49*0Sstevel@tonic-gate =head1 CV Manipulation Functions 50*0Sstevel@tonic-gate 51*0Sstevel@tonic-gate =for apidoc Am|HV*|CvSTASH|CV* cv 52*0Sstevel@tonic-gate Returns the stash of the CV. 53*0Sstevel@tonic-gate 54*0Sstevel@tonic-gate =cut 55*0Sstevel@tonic-gate */ 56*0Sstevel@tonic-gate 57*0Sstevel@tonic-gate #define Nullcv Null(CV*) 58*0Sstevel@tonic-gate 59*0Sstevel@tonic-gate #define CvSTASH(sv) ((XPVCV*)SvANY(sv))->xcv_stash 60*0Sstevel@tonic-gate #define CvSTART(sv) ((XPVCV*)SvANY(sv))->xcv_start 61*0Sstevel@tonic-gate #define CvROOT(sv) ((XPVCV*)SvANY(sv))->xcv_root 62*0Sstevel@tonic-gate #define CvXSUB(sv) ((XPVCV*)SvANY(sv))->xcv_xsub 63*0Sstevel@tonic-gate #define CvXSUBANY(sv) ((XPVCV*)SvANY(sv))->xcv_xsubany 64*0Sstevel@tonic-gate #define CvGV(sv) ((XPVCV*)SvANY(sv))->xcv_gv 65*0Sstevel@tonic-gate #define CvFILE(sv) ((XPVCV*)SvANY(sv))->xcv_file 66*0Sstevel@tonic-gate #ifdef USE_ITHREADS 67*0Sstevel@tonic-gate # define CvFILE_set_from_cop(sv, cop) (CvFILE(sv) = savepv(CopFILE(cop))) 68*0Sstevel@tonic-gate #else 69*0Sstevel@tonic-gate # define CvFILE_set_from_cop(sv, cop) (CvFILE(sv) = CopFILE(cop)) 70*0Sstevel@tonic-gate #endif 71*0Sstevel@tonic-gate #define CvFILEGV(sv) (gv_fetchfile(CvFILE(sv))) 72*0Sstevel@tonic-gate #define CvDEPTH(sv) ((XPVCV*)SvANY(sv))->xcv_depth 73*0Sstevel@tonic-gate #define CvPADLIST(sv) ((XPVCV*)SvANY(sv))->xcv_padlist 74*0Sstevel@tonic-gate #define CvOUTSIDE(sv) ((XPVCV*)SvANY(sv))->xcv_outside 75*0Sstevel@tonic-gate #ifdef USE_5005THREADS 76*0Sstevel@tonic-gate #define CvMUTEXP(sv) ((XPVCV*)SvANY(sv))->xcv_mutexp 77*0Sstevel@tonic-gate #define CvOWNER(sv) ((XPVCV*)SvANY(sv))->xcv_owner 78*0Sstevel@tonic-gate #endif /* USE_5005THREADS */ 79*0Sstevel@tonic-gate #define CvFLAGS(sv) ((XPVCV*)SvANY(sv))->xcv_flags 80*0Sstevel@tonic-gate #define CvOUTSIDE_SEQ(sv) ((XPVCV*)SvANY(sv))->xcv_outside_seq 81*0Sstevel@tonic-gate 82*0Sstevel@tonic-gate #define CVf_CLONE 0x0001 /* anon CV uses external lexicals */ 83*0Sstevel@tonic-gate #define CVf_CLONED 0x0002 /* a clone of one of those */ 84*0Sstevel@tonic-gate #define CVf_ANON 0x0004 /* CvGV() can't be trusted */ 85*0Sstevel@tonic-gate #define CVf_OLDSTYLE 0x0008 86*0Sstevel@tonic-gate #define CVf_UNIQUE 0x0010 /* sub is only called once (eg PL_main_cv, 87*0Sstevel@tonic-gate * require, eval). Not to be confused 88*0Sstevel@tonic-gate * with the GVf_UNIQUE flag associated 89*0Sstevel@tonic-gate * with the :unique attribute */ 90*0Sstevel@tonic-gate #define CVf_NODEBUG 0x0020 /* no DB::sub indirection for this CV 91*0Sstevel@tonic-gate (esp. useful for special XSUBs) */ 92*0Sstevel@tonic-gate #define CVf_METHOD 0x0040 /* CV is explicitly marked as a method */ 93*0Sstevel@tonic-gate #define CVf_LOCKED 0x0080 /* CV locks itself or first arg on entry */ 94*0Sstevel@tonic-gate #define CVf_LVALUE 0x0100 /* CV return value can be used as lvalue */ 95*0Sstevel@tonic-gate #define CVf_CONST 0x0200 /* inlinable sub */ 96*0Sstevel@tonic-gate #define CVf_WEAKOUTSIDE 0x0400 /* CvOUTSIDE isn't ref counted */ 97*0Sstevel@tonic-gate 98*0Sstevel@tonic-gate /* This symbol for optimised communication between toke.c and op.c: */ 99*0Sstevel@tonic-gate #define CVf_BUILTIN_ATTRS (CVf_METHOD|CVf_LOCKED|CVf_LVALUE) 100*0Sstevel@tonic-gate 101*0Sstevel@tonic-gate #define CvCLONE(cv) (CvFLAGS(cv) & CVf_CLONE) 102*0Sstevel@tonic-gate #define CvCLONE_on(cv) (CvFLAGS(cv) |= CVf_CLONE) 103*0Sstevel@tonic-gate #define CvCLONE_off(cv) (CvFLAGS(cv) &= ~CVf_CLONE) 104*0Sstevel@tonic-gate 105*0Sstevel@tonic-gate #define CvCLONED(cv) (CvFLAGS(cv) & CVf_CLONED) 106*0Sstevel@tonic-gate #define CvCLONED_on(cv) (CvFLAGS(cv) |= CVf_CLONED) 107*0Sstevel@tonic-gate #define CvCLONED_off(cv) (CvFLAGS(cv) &= ~CVf_CLONED) 108*0Sstevel@tonic-gate 109*0Sstevel@tonic-gate #define CvANON(cv) (CvFLAGS(cv) & CVf_ANON) 110*0Sstevel@tonic-gate #define CvANON_on(cv) (CvFLAGS(cv) |= CVf_ANON) 111*0Sstevel@tonic-gate #define CvANON_off(cv) (CvFLAGS(cv) &= ~CVf_ANON) 112*0Sstevel@tonic-gate 113*0Sstevel@tonic-gate #ifdef PERL_XSUB_OLDSTYLE 114*0Sstevel@tonic-gate #define CvOLDSTYLE(cv) (CvFLAGS(cv) & CVf_OLDSTYLE) 115*0Sstevel@tonic-gate #define CvOLDSTYLE_on(cv) (CvFLAGS(cv) |= CVf_OLDSTYLE) 116*0Sstevel@tonic-gate #define CvOLDSTYLE_off(cv) (CvFLAGS(cv) &= ~CVf_OLDSTYLE) 117*0Sstevel@tonic-gate #endif 118*0Sstevel@tonic-gate 119*0Sstevel@tonic-gate #define CvUNIQUE(cv) (CvFLAGS(cv) & CVf_UNIQUE) 120*0Sstevel@tonic-gate #define CvUNIQUE_on(cv) (CvFLAGS(cv) |= CVf_UNIQUE) 121*0Sstevel@tonic-gate #define CvUNIQUE_off(cv) (CvFLAGS(cv) &= ~CVf_UNIQUE) 122*0Sstevel@tonic-gate 123*0Sstevel@tonic-gate #define CvNODEBUG(cv) (CvFLAGS(cv) & CVf_NODEBUG) 124*0Sstevel@tonic-gate #define CvNODEBUG_on(cv) (CvFLAGS(cv) |= CVf_NODEBUG) 125*0Sstevel@tonic-gate #define CvNODEBUG_off(cv) (CvFLAGS(cv) &= ~CVf_NODEBUG) 126*0Sstevel@tonic-gate 127*0Sstevel@tonic-gate #define CvMETHOD(cv) (CvFLAGS(cv) & CVf_METHOD) 128*0Sstevel@tonic-gate #define CvMETHOD_on(cv) (CvFLAGS(cv) |= CVf_METHOD) 129*0Sstevel@tonic-gate #define CvMETHOD_off(cv) (CvFLAGS(cv) &= ~CVf_METHOD) 130*0Sstevel@tonic-gate 131*0Sstevel@tonic-gate #define CvLOCKED(cv) (CvFLAGS(cv) & CVf_LOCKED) 132*0Sstevel@tonic-gate #define CvLOCKED_on(cv) (CvFLAGS(cv) |= CVf_LOCKED) 133*0Sstevel@tonic-gate #define CvLOCKED_off(cv) (CvFLAGS(cv) &= ~CVf_LOCKED) 134*0Sstevel@tonic-gate 135*0Sstevel@tonic-gate #define CvLVALUE(cv) (CvFLAGS(cv) & CVf_LVALUE) 136*0Sstevel@tonic-gate #define CvLVALUE_on(cv) (CvFLAGS(cv) |= CVf_LVALUE) 137*0Sstevel@tonic-gate #define CvLVALUE_off(cv) (CvFLAGS(cv) &= ~CVf_LVALUE) 138*0Sstevel@tonic-gate 139*0Sstevel@tonic-gate #define CvEVAL(cv) (CvUNIQUE(cv) && !SvFAKE(cv)) 140*0Sstevel@tonic-gate #define CvEVAL_on(cv) (CvUNIQUE_on(cv),SvFAKE_off(cv)) 141*0Sstevel@tonic-gate #define CvEVAL_off(cv) CvUNIQUE_off(cv) 142*0Sstevel@tonic-gate 143*0Sstevel@tonic-gate /* BEGIN|CHECK|INIT|END */ 144*0Sstevel@tonic-gate #define CvSPECIAL(cv) (CvUNIQUE(cv) && SvFAKE(cv)) 145*0Sstevel@tonic-gate #define CvSPECIAL_on(cv) (CvUNIQUE_on(cv),SvFAKE_on(cv)) 146*0Sstevel@tonic-gate #define CvSPECIAL_off(cv) (CvUNIQUE_off(cv),SvFAKE_off(cv)) 147*0Sstevel@tonic-gate 148*0Sstevel@tonic-gate #define CvCONST(cv) (CvFLAGS(cv) & CVf_CONST) 149*0Sstevel@tonic-gate #define CvCONST_on(cv) (CvFLAGS(cv) |= CVf_CONST) 150*0Sstevel@tonic-gate #define CvCONST_off(cv) (CvFLAGS(cv) &= ~CVf_CONST) 151*0Sstevel@tonic-gate 152*0Sstevel@tonic-gate #define CvWEAKOUTSIDE(cv) (CvFLAGS(cv) & CVf_WEAKOUTSIDE) 153*0Sstevel@tonic-gate #define CvWEAKOUTSIDE_on(cv) (CvFLAGS(cv) |= CVf_WEAKOUTSIDE) 154*0Sstevel@tonic-gate #define CvWEAKOUTSIDE_off(cv) (CvFLAGS(cv) &= ~CVf_WEAKOUTSIDE) 155*0Sstevel@tonic-gate 156*0Sstevel@tonic-gate 157*0Sstevel@tonic-gate /* 158*0Sstevel@tonic-gate =head1 CV reference counts and CvOUTSIDE 159*0Sstevel@tonic-gate 160*0Sstevel@tonic-gate =for apidoc m|bool|CvWEAKOUTSIDE|CV *cv 161*0Sstevel@tonic-gate 162*0Sstevel@tonic-gate Each CV has a pointer, C<CvOUTSIDE()>, to its lexically enclosing 163*0Sstevel@tonic-gate CV (if any). Because pointers to anonymous sub prototypes are 164*0Sstevel@tonic-gate stored in C<&> pad slots, it is a possible to get a circular reference, 165*0Sstevel@tonic-gate with the parent pointing to the child and vice-versa. To avoid the 166*0Sstevel@tonic-gate ensuing memory leak, we do not increment the reference count of the CV 167*0Sstevel@tonic-gate pointed to by C<CvOUTSIDE> in the I<one specific instance> that the parent 168*0Sstevel@tonic-gate has a C<&> pad slot pointing back to us. In this case, we set the 169*0Sstevel@tonic-gate C<CvWEAKOUTSIDE> flag in the child. This allows us to determine under what 170*0Sstevel@tonic-gate circumstances we should decrement the refcount of the parent when freeing 171*0Sstevel@tonic-gate the child. 172*0Sstevel@tonic-gate 173*0Sstevel@tonic-gate There is a further complication with non-closure anonymous subs (ie those 174*0Sstevel@tonic-gate that do not refer to any lexicals outside that sub). In this case, the 175*0Sstevel@tonic-gate anonymous prototype is shared rather than being cloned. This has the 176*0Sstevel@tonic-gate consequence that the parent may be freed while there are still active 177*0Sstevel@tonic-gate children, eg 178*0Sstevel@tonic-gate 179*0Sstevel@tonic-gate BEGIN { $a = sub { eval '$x' } } 180*0Sstevel@tonic-gate 181*0Sstevel@tonic-gate In this case, the BEGIN is freed immediately after execution since there 182*0Sstevel@tonic-gate are no active references to it: the anon sub prototype has 183*0Sstevel@tonic-gate C<CvWEAKOUTSIDE> set since it's not a closure, and $a points to the same 184*0Sstevel@tonic-gate CV, so it doesn't contribute to BEGIN's refcount either. When $a is 185*0Sstevel@tonic-gate executed, the C<eval '$x'> causes the chain of C<CvOUTSIDE>s to be followed, 186*0Sstevel@tonic-gate and the freed BEGIN is accessed. 187*0Sstevel@tonic-gate 188*0Sstevel@tonic-gate To avoid this, whenever a CV and its associated pad is freed, any 189*0Sstevel@tonic-gate C<&> entries in the pad are explicitly removed from the pad, and if the 190*0Sstevel@tonic-gate refcount of the pointed-to anon sub is still positive, then that 191*0Sstevel@tonic-gate child's C<CvOUTSIDE> is set to point to its grandparent. This will only 192*0Sstevel@tonic-gate occur in the single specific case of a non-closure anon prototype 193*0Sstevel@tonic-gate having one or more active references (such as C<$a> above). 194*0Sstevel@tonic-gate 195*0Sstevel@tonic-gate One other thing to consider is that a CV may be merely undefined 196*0Sstevel@tonic-gate rather than freed, eg C<undef &foo>. In this case, its refcount may 197*0Sstevel@tonic-gate not have reached zero, but we still delete its pad and its C<CvROOT> etc. 198*0Sstevel@tonic-gate Since various children may still have their C<CvOUTSIDE> pointing at this 199*0Sstevel@tonic-gate undefined CV, we keep its own C<CvOUTSIDE> for the time being, so that 200*0Sstevel@tonic-gate the chain of lexical scopes is unbroken. For example, the following 201*0Sstevel@tonic-gate should print 123: 202*0Sstevel@tonic-gate 203*0Sstevel@tonic-gate my $x = 123; 204*0Sstevel@tonic-gate sub tmp { sub { eval '$x' } } 205*0Sstevel@tonic-gate my $a = tmp(); 206*0Sstevel@tonic-gate undef &tmp; 207*0Sstevel@tonic-gate print $a->(); 208*0Sstevel@tonic-gate 209*0Sstevel@tonic-gate =cut 210*0Sstevel@tonic-gate */ 211