]> perl5.git.perl.org Git - perl5.git/blob - cv.h This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Deparse: exclude two new test files
[perl5.git] / cv.h
1 /*    cv.h
2  *
3  *    Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
4  *    2002, 2003, 2004, 2005, 2006, 2007, 2008 by Larry Wall and others
5  *
6  *    You may distribute under the terms of either the GNU General Public
7  *    License or the Artistic License, as specified in the README file.
8  *
9  */
10
11 /* This structure must match the beginning of XPVFM in sv.h  */
12
13 struct xpvcv {
14     _XPV_HEAD;
15     _XPVCV_COMMON;
16 };
17
18 /*
19 =for apidoc_section $CV
20
21 =for apidoc      Am|CV *|CvREFCNT_inc|CV *cv
22 =for apidoc_item   |CV *|CvREFCNT_inc_simple|CV *cv
23 =for apidoc_item   |CV *|CvREFCNT_inc_simple_NN|CV *cv
24
25 These all increment the reference count of the given SV, which must be a CV.
26 They are useful when assigning the result into a typed pointer as they avoid
27 the need to cast the result to the appropriate type.
28
29 =cut
30 */
31
32 #define CvREFCNT_inc(cv)            ((CV *)SvREFCNT_inc((SV *)cv))
33 #define CvREFCNT_inc_simple(cv)     ((CV *)SvREFCNT_inc_simple((SV *)cv))
34 #define CvREFCNT_inc_simple_NN(cv)  ((CV *)SvREFCNT_inc_simple_NN((SV *)cv))
35
36 /*
37 =for apidoc Ayh||CV
38
39 =for apidoc ADmnU||Nullcv
40 Null CV pointer.
41
42 (deprecated - use C<(CV *)NULL> instead)
43
44 =for apidoc Am|HV*|CvSTASH|CV* cv
45 Returns the stash of the CV.  A stash is the symbol table hash, containing
46 the package-scoped variables in the package where the subroutine was defined.
47 For more information, see L<perlguts>.
48
49 This also has a special use with XS AUTOLOAD subs.
50 See L<perlguts/Autoloading with XSUBs>.
51
52 =cut
53 */
54
55 #ifndef PERL_CORE
56 #  define Nullcv Null(CV*)
57 #endif
58
59 #define CvSTASH(sv)     (MUTABLE_HV(((XPVCV*)MUTABLE_PTR(SvANY(sv)))->xcv_stash))
60 #define CvSTASH_set(cv,st) Perl_cvstash_set(aTHX_ cv, st)
61 #define CvSTART(sv)     ((XPVCV*)MUTABLE_PTR(SvANY(sv)))->xcv_start_u.xcv_start
62 #define CvROOT(sv)      ((XPVCV*)MUTABLE_PTR(SvANY(sv)))->xcv_root_u.xcv_root
63 #define CvXSUB(sv)      ((XPVCV*)MUTABLE_PTR(SvANY(sv)))->xcv_root_u.xcv_xsub
64 #define CvXSUBANY(sv)   ((XPVCV*)MUTABLE_PTR(SvANY(sv)))->xcv_start_u.xcv_xsubany
65 #define CvGV(sv)        Perl_CvGV(aTHX_ (CV *)(sv))
66 #define CvGV_set(cv,gv) Perl_cvgv_set(aTHX_ cv, gv)
67 #define CvHASGV(cv)     cBOOL(SvANY(cv)->xcv_gv_u.xcv_gv)
68 #define CvFILE(sv)      ((XPVCV*)MUTABLE_PTR(SvANY(sv)))->xcv_file
69 #ifdef USE_ITHREADS
70 #  define CvFILE_set_from_cop(sv, cop)  \
71     (CvFILE(sv) = savepv(CopFILE(cop)), CvDYNFILE_on(sv))
72 #else
73 #  define CvFILE_set_from_cop(sv, cop)  \
74     (CvFILE(sv) = CopFILE(cop), CvDYNFILE_off(sv))
75 #endif
76 #define CvFILEGV(sv)    (gv_fetchfile(CvFILE(sv)))
77 #define CvDEPTH(sv)     (*Perl_CvDEPTH((const CV *)sv))
78 /* For use when you only have a XPVCV*, not a real CV*.
79    Must be assert protected as in Perl_CvDEPTH before use. */
80 #define CvDEPTHunsafe(sv) ((XPVCV*)MUTABLE_PTR(SvANY(sv)))->xcv_depth
81
82 /* these CvPADLIST/CvRESERVED asserts can be reverted one day, once stabilized */
83 #define CvPADLIST(sv)     (*(assert_(!CvISXSUB((CV*)(sv))) \
84         &(((XPVCV*)MUTABLE_PTR(SvANY(sv)))->xcv_padlist_u.xcv_padlist)))
85 /* CvPADLIST_set is not public API, it can be removed one day, once stabilized */
86 #ifdef DEBUGGING
87 #  define CvPADLIST_set(sv, padlist) Perl_set_padlist((CV*)sv, padlist)
88 #else
89 #  define CvPADLIST_set(sv, padlist) (CvPADLIST(sv) = (padlist))
90 #endif
91 #define CvHSCXT(sv)       *(assert_(CvISXSUB((CV*)(sv))) \
92         &(((XPVCV*)MUTABLE_PTR(SvANY(sv)))->xcv_padlist_u.xcv_hscxt))
93 #ifdef DEBUGGING
94 #  if PTRSIZE == 8
95 #    define PoisonPADLIST(sv) \
96         (((XPVCV*)MUTABLE_PTR(SvANY(sv)))->xcv_padlist_u.xcv_padlist = (PADLIST *)UINT64_C(0xEFEFEFEFEFEFEFEF))
97 #  elif PTRSIZE == 4
98 #    define PoisonPADLIST(sv) \
99         (((XPVCV*)MUTABLE_PTR(SvANY(sv)))->xcv_padlist_u.xcv_padlist = (PADLIST *)0xEFEFEFEF)
100 #  else
101 #    error unknown pointer size
102 #  endif
103 #else
104 #  define PoisonPADLIST(sv) NOOP
105 #endif
106
107 #define CvOUTSIDE(sv)     ((XPVCV*)MUTABLE_PTR(SvANY(sv)))->xcv_outside
108 #define CvOUTSIDE_SEQ(sv) ((XPVCV*)MUTABLE_PTR(SvANY(sv)))->xcv_outside_seq
109 #define CvFLAGS(sv)       ((XPVCV*)MUTABLE_PTR(SvANY(sv)))->xcv_flags
110
111 /* These two are sometimes called on non-CVs */
112 #define CvPROTO(sv)                               \
113         (                                          \
114          SvPOK(sv)                                  \
115           ? SvTYPE(sv) == SVt_PVCV && CvAUTOLOAD(sv) \
116              ? SvEND(sv)+1 : SvPVX_const(sv)          \
117           : NULL                                       \
118         )
119 #define CvPROTOLEN(sv)                            \
120         (                                          \
121          SvPOK(sv)                                  \
122           ? SvTYPE(sv) == SVt_PVCV && CvAUTOLOAD(sv) \
123              ? SvLEN(sv)-SvCUR(sv)-2                  \
124              : SvCUR(sv)                               \
125           : 0                                           \
126         )
127
128 /* CV has the `:method` attribute. This used to be called CVf_METHOD but is
129  * renamed to avoid collision with CVf_IsMETHOD */
130 #define CVf_NOWARN_AMBIGUOUS    0x0001
131
132 #define CVf_LVALUE      0x0002  /* CV return value can be used as lvalue */
133 #define CVf_CONST       0x0004  /* inlinable sub */
134 #define CVf_ISXSUB      0x0008  /* CV is an XSUB, not pure perl.  */
135
136 #define CVf_WEAKOUTSIDE 0x0010  /* CvOUTSIDE isn't ref counted */
137 #define CVf_CLONE       0x0020  /* anon CV uses external lexicals */
138 #define CVf_CLONED      0x0040  /* a clone of one of those */
139 #define CVf_ANON        0x0080  /* CV is not pointed to by a GV */
140 #define CVf_UNIQUE      0x0100  /* sub is only called once (eg PL_main_cv,
141                                    require, eval). */
142 #define CVf_NODEBUG     0x0200  /* no DB::sub indirection for this CV
143                                    (esp. useful for special XSUBs) */
144 #define CVf_CVGV_RC     0x0400  /* CvGV is reference counted */
145 #if defined(PERL_CORE) || defined(PERL_EXT)
146 # define CVf_SLABBED    0x0800  /* Holds refcount on op slab  */
147 #endif
148 #define CVf_DYNFILE     0x1000  /* The filename is malloced  */
149 #define CVf_AUTOLOAD    0x2000  /* SvPVX contains AUTOLOADed sub name  */
150 #define CVf_HASEVAL     0x4000  /* contains string eval  */
151 #define CVf_NAMED       0x8000  /* Has a name HEK */
152 #define CVf_LEXICAL     0x10000 /* Omit package from name */
153 #define CVf_ANONCONST   0x20000 /* :const - create anonconst op */
154 #define CVf_SIGNATURE   0x40000 /* CV uses a signature */
155 #define CVf_REFCOUNTED_ANYSV 0x80000 /* CvXSUBANY().any_sv is refcounted */
156 #define CVf_IsMETHOD    0x100000 /* CV is a (real) method of a real class. Not
157                                    to be confused with what used to be called
158                                    CVf_METHOD; now CVf_NOWARN_AMBIGUOUS */
159 #define CVf_XS_RCSTACK  0x200000 /* the XS function understands a
160                                     reference-counted stack */
161 #define CVf_EVAL_COMPILED 0x400000 /* an eval CV is fully compiled */
162
163 /* This symbol for optimised communication between toke.c and op.c: */
164 #define CVf_BUILTIN_ATTRS       (CVf_NOWARN_AMBIGUOUS|CVf_LVALUE|CVf_ANONCONST)
165
166 #define CvCLONE(cv)             (CvFLAGS(cv) & CVf_CLONE)
167 #define CvCLONE_on(cv)          (CvFLAGS(cv) |= CVf_CLONE)
168 #define CvCLONE_off(cv)         (CvFLAGS(cv) &= ~CVf_CLONE)
169
170 #define CvCLONED(cv)            (CvFLAGS(cv) & CVf_CLONED)
171 #define CvCLONED_on(cv)         (CvFLAGS(cv) |= CVf_CLONED)
172 #define CvCLONED_off(cv)        (CvFLAGS(cv) &= ~CVf_CLONED)
173
174 #define CvANON(cv)              (CvFLAGS(cv) & CVf_ANON)
175 #define CvANON_on(cv)           (CvFLAGS(cv) |= CVf_ANON)
176 #define CvANON_off(cv)          (CvFLAGS(cv) &= ~CVf_ANON)
177
178 /* CvEVAL or CvSPECIAL */
179 #define CvUNIQUE(cv)            (CvFLAGS(cv) & CVf_UNIQUE)
180 #define CvUNIQUE_on(cv)         (CvFLAGS(cv) |= CVf_UNIQUE)
181 #define CvUNIQUE_off(cv)        (CvFLAGS(cv) &= ~CVf_UNIQUE)
182
183 #define CvNODEBUG(cv)           (CvFLAGS(cv) & CVf_NODEBUG)
184 #define CvNODEBUG_on(cv)        (CvFLAGS(cv) |= CVf_NODEBUG)
185 #define CvNODEBUG_off(cv)       (CvFLAGS(cv) &= ~CVf_NODEBUG)
186
187 #define CvNOWARN_AMBIGUOUS(cv)          (CvFLAGS(cv) & CVf_NOWARN_AMBIGUOUS)
188 #define CvNOWARN_AMBIGUOUS_on(cv)       (CvFLAGS(cv) |= CVf_NOWARN_AMBIGUOUS)
189 #define CvNOWARN_AMBIGUOUS_off(cv)      (CvFLAGS(cv) &= ~CVf_NOWARN_AMBIGUOUS)
190
191 #define CvLVALUE(cv)            (CvFLAGS(cv) & CVf_LVALUE)
192 #define CvLVALUE_on(cv)         (CvFLAGS(cv) |= CVf_LVALUE)
193 #define CvLVALUE_off(cv)        (CvFLAGS(cv) &= ~CVf_LVALUE)
194
195 /* eval or PL_main_cv */
196 #define CvEVAL(cv)              (CvUNIQUE(cv) && !SvFAKE(cv))
197 #define CvEVAL_on(cv)           (CvUNIQUE_on(cv),SvFAKE_off(cv))
198 #define CvEVAL_off(cv)          CvUNIQUE_off(cv)
199
200 /* BEGIN|CHECK|INIT|UNITCHECK|END */
201 #define CvSPECIAL(cv)           (CvUNIQUE(cv) && SvFAKE(cv))
202 #define CvSPECIAL_on(cv)        (CvUNIQUE_on(cv),SvFAKE_on(cv))
203 #define CvSPECIAL_off(cv)       (CvUNIQUE_off(cv),SvFAKE_off(cv))
204
205 #define CvCONST(cv)             (CvFLAGS(cv) & CVf_CONST)
206 #define CvCONST_on(cv)          (CvFLAGS(cv) |= CVf_CONST)
207 #define CvCONST_off(cv)         (CvFLAGS(cv) &= ~CVf_CONST)
208
209 #define CvWEAKOUTSIDE(cv)       (CvFLAGS(cv) & CVf_WEAKOUTSIDE)
210 #define CvWEAKOUTSIDE_on(cv)    (CvFLAGS(cv) |= CVf_WEAKOUTSIDE)
211 #define CvWEAKOUTSIDE_off(cv)   (CvFLAGS(cv) &= ~CVf_WEAKOUTSIDE)
212
213 #define CvISXSUB(cv)            (CvFLAGS(cv) & CVf_ISXSUB)
214 #define CvISXSUB_on(cv)         (CvFLAGS(cv) |= CVf_ISXSUB)
215 #define CvISXSUB_off(cv)        (CvFLAGS(cv) &= ~CVf_ISXSUB)
216
217 #define CvCVGV_RC(cv)           (CvFLAGS(cv) & CVf_CVGV_RC)
218 #define CvCVGV_RC_on(cv)        (CvFLAGS(cv) |= CVf_CVGV_RC)
219 #define CvCVGV_RC_off(cv)       (CvFLAGS(cv) &= ~CVf_CVGV_RC)
220
221 #ifdef PERL_CORE
222 # define CvSLABBED(cv)          (CvFLAGS(cv) & CVf_SLABBED)
223 # define CvSLABBED_on(cv)       (CvFLAGS(cv) |= CVf_SLABBED)
224 # define CvSLABBED_off(cv)      (CvFLAGS(cv) &= ~CVf_SLABBED)
225 #endif
226
227 #define CvDYNFILE(cv)           (CvFLAGS(cv) & CVf_DYNFILE)
228 #define CvDYNFILE_on(cv)        (CvFLAGS(cv) |= CVf_DYNFILE)
229 #define CvDYNFILE_off(cv)       (CvFLAGS(cv) &= ~CVf_DYNFILE)
230
231 #define CvAUTOLOAD(cv)          (CvFLAGS(cv) & CVf_AUTOLOAD)
232 #define CvAUTOLOAD_on(cv)       (CvFLAGS(cv) |= CVf_AUTOLOAD)
233 #define CvAUTOLOAD_off(cv)      (CvFLAGS(cv) &= ~CVf_AUTOLOAD)
234
235 #define CvHASEVAL(cv)           (CvFLAGS(cv) & CVf_HASEVAL)
236 #define CvHASEVAL_on(cv)        (CvFLAGS(cv) |= CVf_HASEVAL)
237 #define CvHASEVAL_off(cv)       (CvFLAGS(cv) &= ~CVf_HASEVAL)
238
239 #define CvNAMED(cv)             (CvFLAGS(cv) & CVf_NAMED)
240 #define CvNAMED_on(cv)          (CvFLAGS(cv) |= CVf_NAMED)
241 #define CvNAMED_off(cv)         (CvFLAGS(cv) &= ~CVf_NAMED)
242
243 #define CvLEXICAL(cv)           (CvFLAGS(cv) & CVf_LEXICAL)
244 #define CvLEXICAL_on(cv)        (CvFLAGS(cv) |= CVf_LEXICAL)
245 #define CvLEXICAL_off(cv)       (CvFLAGS(cv) &= ~CVf_LEXICAL)
246
247 #define CvANONCONST(cv)         (CvFLAGS(cv) & CVf_ANONCONST)
248 #define CvANONCONST_on(cv)      (CvFLAGS(cv) |= CVf_ANONCONST)
249 #define CvANONCONST_off(cv)     (CvFLAGS(cv) &= ~CVf_ANONCONST)
250
251 #define CvSIGNATURE(cv)         (CvFLAGS(cv) & CVf_SIGNATURE)
252 #define CvSIGNATURE_on(cv)      (CvFLAGS(cv) |= CVf_SIGNATURE)
253 #define CvSIGNATURE_off(cv)     (CvFLAGS(cv) &= ~CVf_SIGNATURE)
254
255 /*
256
257 =for apidoc m|bool|CvREFCOUNTED_ANYSV|CV *cv
258
259 If true, indicates that the C<CvXSUBANY(cv).any_sv> member contains an SV
260 pointer whose reference count should be decremented when the CV itself is
261 freed.  In addition, C<cv_clone()> will increment the reference count, and
262 C<sv_dup()> will duplicate the entire pointed-to SV if this flag is set.
263
264 Any CV that wraps an XSUB has an C<ANY> union that the XSUB function is free
265 to use for its own purposes.  It may be the case that the code wishes to store
266 an SV in the C<any_sv> member of this union.  By setting this flag, this SV
267 reference will be properly reclaimed or duplicated when the CV itself is.
268
269 =for apidoc m|void|CvREFCOUNTED_ANYSV_on|CV *cv
270
271 Helper macro to turn on the C<CvREFCOUNTED_ANYSV> flag.
272
273 =for apidoc m|void|CvREFCOUNTED_ANYSV_off|CV *cv
274
275 Helper macro to turn off the C<CvREFCOUNTED_ANYSV> flag.
276
277 =cut
278 */
279
280 #define CvREFCOUNTED_ANYSV(cv)          (CvFLAGS(cv) & CVf_REFCOUNTED_ANYSV)
281 #define CvREFCOUNTED_ANYSV_on(cv)       (CvFLAGS(cv) |= CVf_REFCOUNTED_ANYSV)
282 #define CvREFCOUNTED_ANYSV_off(cv)      (CvFLAGS(cv) &= ~CVf_REFCOUNTED_ANYSV)
283
284 #define CvIsMETHOD(cv)          (CvFLAGS(cv) & CVf_IsMETHOD)
285 #define CvIsMETHOD_on(cv)       (CvFLAGS(cv) |= CVf_IsMETHOD)
286 #define CvIsMETHOD_off(cv)      (CvFLAGS(cv) &= ~CVf_IsMETHOD)
287
288 #define CvXS_RCSTACK(cv)        (CvFLAGS(cv) & CVf_XS_RCSTACK)
289 #define CvXS_RCSTACK_on(cv)     (CvFLAGS(cv) |= CVf_XS_RCSTACK)
290 #define CvXS_RCSTACK_off(cv)    (CvFLAGS(cv) &= ~CVf_XS_RCSTACK)
291
292 #define CvEVAL_COMPILED(cv)     (CvFLAGS(cv) & CVf_EVAL_COMPILED)
293 #define CvEVAL_COMPILED_on(cv)  (CvFLAGS(cv) |= CVf_EVAL_COMPILED)
294 #define CvEVAL_COMPILED_off(cv) (CvFLAGS(cv) &= ~CVf_EVAL_COMPILED)
295
296 /* Back-compat */
297 #ifndef PERL_CORE
298 #  define CVf_METHOD            CVf_NOWARN_AMBIGUOUS
299 #  define CvMETHOD(cv)          CvNOWARN_AMBIGUOUS(cv)
300 #  define CvMETHOD_on(cv)       CvNOWARN_AMBIGUOUS_on(cv)
301 #  define CvMETHOD_off(cv)      CvNOWARN_AMBIGUOUS_off(cv)
302 #endif
303
304 /* Flags for newXS_flags  */
305 #define XS_DYNAMIC_FILENAME     0x01    /* The filename isn't static  */
306
307 PERL_STATIC_INLINE HEK *
308 CvNAME_HEK(CV *sv)
309 {
310     return CvNAMED(sv)
311         ? ((XPVCV*)MUTABLE_PTR(SvANY(sv)))->xcv_gv_u.xcv_hek
312         : 0;
313 }
314
315 /* helper for the common pattern:
316    CvNAMED(sv) ? CvNAME_HEK((CV *)sv) : GvNAME_HEK(CvGV(sv))
317 */
318 #define CvGvNAME_HEK(sv) ( \
319         CvNAMED((CV*)sv) ? \
320             ((XPVCV*)MUTABLE_PTR(SvANY((SV*)sv)))->xcv_gv_u.xcv_hek\
321             : GvNAME_HEK(CvGV( (SV*) sv)) \
322         )
323
324 /* This lowers the reference count of the previous value, but does *not*
325    increment the reference count of the new value. */
326 #define CvNAME_HEK_set(cv, hek) ( \
327         CvNAME_HEK((CV *)(cv))                                           \
328             ? unshare_hek(SvANY((CV *)(cv))->xcv_gv_u.xcv_hek)    \
329             : (void)0,                                             \
330         ((XPVCV*)MUTABLE_PTR(SvANY(cv)))->xcv_gv_u.xcv_hek = (hek), \
331         CvNAMED_on(cv)                                               \
332     )
333
334 /*
335
336 =for apidoc m|bool|CvWEAKOUTSIDE|CV *cv
337
338 Each CV has a pointer, C<CvOUTSIDE()>, to its lexically enclosing
339 CV (if any).  Because pointers to anonymous sub prototypes are
340 stored in C<&> pad slots, it is a possible to get a circular reference,
341 with the parent pointing to the child and vice-versa.  To avoid the
342 ensuing memory leak, we do not increment the reference count of the CV
343 pointed to by C<CvOUTSIDE> in the I<one specific instance> that the parent
344 has a C<&> pad slot pointing back to us.  In this case, we set the
345 C<CvWEAKOUTSIDE> flag in the child.  This allows us to determine under what
346 circumstances we should decrement the refcount of the parent when freeing
347 the child.
348
349 There is a further complication with non-closure anonymous subs (i.e. those
350 that do not refer to any lexicals outside that sub).  In this case, the
351 anonymous prototype is shared rather than being cloned.  This has the
352 consequence that the parent may be freed while there are still active
353 children, I<e.g.>,
354
355     BEGIN { $a = sub { eval '$x' } }
356
357 In this case, the BEGIN is freed immediately after execution since there
358 are no active references to it: the anon sub prototype has
359 C<CvWEAKOUTSIDE> set since it's not a closure, and $a points to the same
360 CV, so it doesn't contribute to BEGIN's refcount either.  When $a is
361 executed, the C<eval '$x'> causes the chain of C<CvOUTSIDE>s to be followed,
362 and the freed BEGIN is accessed.
363
364 To avoid this, whenever a CV and its associated pad is freed, any
365 C<&> entries in the pad are explicitly removed from the pad, and if the
366 refcount of the pointed-to anon sub is still positive, then that
367 child's C<CvOUTSIDE> is set to point to its grandparent.  This will only
368 occur in the single specific case of a non-closure anon prototype
369 having one or more active references (such as C<$a> above).
370
371 One other thing to consider is that a CV may be merely undefined
372 rather than freed, eg C<undef &foo>.  In this case, its refcount may
373 not have reached zero, but we still delete its pad and its C<CvROOT> etc.
374 Since various children may still have their C<CvOUTSIDE> pointing at this
375 undefined CV, we keep its own C<CvOUTSIDE> for the time being, so that
376 the chain of lexical scopes is unbroken.  For example, the following
377 should print 123:
378
379     my $x = 123;
380     sub tmp { sub { eval '$x' } }
381     my $a = tmp();
382     undef &tmp;
383     print  $a->();
384
385 =cut
386 */
387
388 typedef OP *(*Perl_call_checker)(pTHX_ OP *, GV *, SV *);
389
390 #define CALL_CHECKER_REQUIRE_GV MGf_REQUIRE_GV
391
392 #define CV_NAME_NOTQUAL         1
393
394 #ifdef PERL_CORE
395 # define CV_UNDEF_KEEP_NAME     1
396 #endif
397
398 /*
399  * ex: set ts=8 sts=4 sw=4 et:
400  */