Upgrade to Tie::File 0.20.
[perl.git] / cv.h
1 /*    cv.h
2  *
3  *    Copyright (c) 1991-2002, Larry Wall
4  *
5  *    You may distribute under the terms of either the GNU General Public
6  *    License or the Artistic License, as specified in the README file.
7  *
8  */
9
10 /* This structure much match XPVCV in B/C.pm and the beginning of XPVFM
11  * in sv.h  */
12
13 struct xpvcv {
14     char *      xpv_pv;         /* pointer to malloced string */
15     STRLEN      xpv_cur;        /* length of xp_pv as a C string */
16     STRLEN      xpv_len;        /* allocated size */
17     IV          xof_off;        /* integer value */
18     NV          xnv_nv;         /* numeric value, if any */
19     MAGIC*      xmg_magic;      /* magic for scalar array */
20     HV*         xmg_stash;      /* class package */
21
22     HV *        xcv_stash;
23     OP *        xcv_start;
24     OP *        xcv_root;
25     void        (*xcv_xsub) (pTHX_ CV*);
26     ANY         xcv_xsubany;
27     GV *        xcv_gv;
28     char *      xcv_file;
29     long        xcv_depth;      /* >= 2 indicates recursive call */
30     AV *        xcv_padlist;
31     CV *        xcv_outside;
32 #ifdef USE_5005THREADS
33     perl_mutex *xcv_mutexp;
34     struct perl_thread *xcv_owner;      /* current owner thread */
35 #endif /* USE_5005THREADS */
36     cv_flags_t  xcv_flags;
37 };
38
39 /*
40 =head1 Handy Values
41
42 =for apidoc AmU||Nullcv
43 Null CV pointer.
44
45 =head1 CV Manipulation Functions
46
47 =for apidoc Am|HV*|CvSTASH|CV* cv
48 Returns the stash of the CV.
49
50 =cut
51 */
52
53 #define Nullcv Null(CV*)
54
55 #define CvSTASH(sv)     ((XPVCV*)SvANY(sv))->xcv_stash
56 #define CvSTART(sv)     ((XPVCV*)SvANY(sv))->xcv_start
57 #define CvROOT(sv)      ((XPVCV*)SvANY(sv))->xcv_root
58 #define CvXSUB(sv)      ((XPVCV*)SvANY(sv))->xcv_xsub
59 #define CvXSUBANY(sv)   ((XPVCV*)SvANY(sv))->xcv_xsubany
60 #define CvGV(sv)        ((XPVCV*)SvANY(sv))->xcv_gv
61 #define CvFILE(sv)      ((XPVCV*)SvANY(sv))->xcv_file
62 #ifdef USE_ITHREADS
63 #  define CvFILE_set_from_cop(sv, cop)  (CvFILE(sv) = savepv(CopFILE(cop)))
64 #else
65 #  define CvFILE_set_from_cop(sv, cop)  (CvFILE(sv) = CopFILE(cop))
66 #endif
67 #define CvFILEGV(sv)    (gv_fetchfile(CvFILE(sv)))
68 #define CvDEPTH(sv)     ((XPVCV*)SvANY(sv))->xcv_depth
69 #define CvPADLIST(sv)   ((XPVCV*)SvANY(sv))->xcv_padlist
70 #define CvOUTSIDE(sv)   ((XPVCV*)SvANY(sv))->xcv_outside
71 #ifdef USE_5005THREADS
72 #define CvMUTEXP(sv)    ((XPVCV*)SvANY(sv))->xcv_mutexp
73 #define CvOWNER(sv)     ((XPVCV*)SvANY(sv))->xcv_owner
74 #endif /* USE_5005THREADS */
75 #define CvFLAGS(sv)     ((XPVCV*)SvANY(sv))->xcv_flags
76
77 #define CVf_CLONE       0x0001  /* anon CV uses external lexicals */
78 #define CVf_CLONED      0x0002  /* a clone of one of those */
79 #define CVf_ANON        0x0004  /* CvGV() can't be trusted */
80 #define CVf_OLDSTYLE    0x0008
81 #define CVf_UNIQUE      0x0010  /* can't be cloned */
82 #define CVf_NODEBUG     0x0020  /* no DB::sub indirection for this CV
83                                    (esp. useful for special XSUBs) */
84 #define CVf_METHOD      0x0040  /* CV is explicitly marked as a method */
85 #define CVf_LOCKED      0x0080  /* CV locks itself or first arg on entry */
86 #define CVf_LVALUE      0x0100  /* CV return value can be used as lvalue */
87 #define CVf_CONST       0x0200  /* inlinable sub */
88
89 #define CvCLONE(cv)             (CvFLAGS(cv) & CVf_CLONE)
90 #define CvCLONE_on(cv)          (CvFLAGS(cv) |= CVf_CLONE)
91 #define CvCLONE_off(cv)         (CvFLAGS(cv) &= ~CVf_CLONE)
92
93 #define CvCLONED(cv)            (CvFLAGS(cv) & CVf_CLONED)
94 #define CvCLONED_on(cv)         (CvFLAGS(cv) |= CVf_CLONED)
95 #define CvCLONED_off(cv)        (CvFLAGS(cv) &= ~CVf_CLONED)
96
97 #define CvANON(cv)              (CvFLAGS(cv) & CVf_ANON)
98 #define CvANON_on(cv)           (CvFLAGS(cv) |= CVf_ANON)
99 #define CvANON_off(cv)          (CvFLAGS(cv) &= ~CVf_ANON)
100
101 #ifdef PERL_XSUB_OLDSTYLE
102 #define CvOLDSTYLE(cv)          (CvFLAGS(cv) & CVf_OLDSTYLE)
103 #define CvOLDSTYLE_on(cv)       (CvFLAGS(cv) |= CVf_OLDSTYLE)
104 #define CvOLDSTYLE_off(cv)      (CvFLAGS(cv) &= ~CVf_OLDSTYLE)
105 #endif
106
107 #define CvUNIQUE(cv)            (CvFLAGS(cv) & CVf_UNIQUE)
108 #define CvUNIQUE_on(cv)         (CvFLAGS(cv) |= CVf_UNIQUE)
109 #define CvUNIQUE_off(cv)        (CvFLAGS(cv) &= ~CVf_UNIQUE)
110
111 #define CvNODEBUG(cv)           (CvFLAGS(cv) & CVf_NODEBUG)
112 #define CvNODEBUG_on(cv)        (CvFLAGS(cv) |= CVf_NODEBUG)
113 #define CvNODEBUG_off(cv)       (CvFLAGS(cv) &= ~CVf_NODEBUG)
114
115 #define CvMETHOD(cv)            (CvFLAGS(cv) & CVf_METHOD)
116 #define CvMETHOD_on(cv)         (CvFLAGS(cv) |= CVf_METHOD)
117 #define CvMETHOD_off(cv)        (CvFLAGS(cv) &= ~CVf_METHOD)
118
119 #define CvLOCKED(cv)            (CvFLAGS(cv) & CVf_LOCKED)
120 #define CvLOCKED_on(cv)         (CvFLAGS(cv) |= CVf_LOCKED)
121 #define CvLOCKED_off(cv)        (CvFLAGS(cv) &= ~CVf_LOCKED)
122
123 #define CvLVALUE(cv)            (CvFLAGS(cv) & CVf_LVALUE)
124 #define CvLVALUE_on(cv)         (CvFLAGS(cv) |= CVf_LVALUE)
125 #define CvLVALUE_off(cv)        (CvFLAGS(cv) &= ~CVf_LVALUE)
126
127 #define CvEVAL(cv)              (CvUNIQUE(cv) && !SvFAKE(cv))
128 #define CvEVAL_on(cv)           (CvUNIQUE_on(cv),SvFAKE_off(cv))
129 #define CvEVAL_off(cv)          CvUNIQUE_off(cv)
130
131 /* BEGIN|INIT|END */
132 #define CvSPECIAL(cv)           (CvUNIQUE(cv) && SvFAKE(cv))
133 #define CvSPECIAL_on(cv)        (CvUNIQUE_on(cv),SvFAKE_on(cv))
134 #define CvSPECIAL_off(cv)       (CvUNIQUE_off(cv),SvFAKE_off(cv))
135
136 #define CvCONST(cv)             (CvFLAGS(cv) & CVf_CONST)
137 #define CvCONST_on(cv)          (CvFLAGS(cv) |= CVf_CONST)
138 #define CvCONST_off(cv)         (CvFLAGS(cv) &= ~CVf_CONST)
139
140 /*
141 =head1 Pad Data Structures
142
143 =for apidoc m|AV *|CvPADLIST|CV *cv
144 CV's can have CvPADLIST(cv) set to point to an AV.
145
146 For these purposes "forms" are a kind-of CV, eval""s are too (except they're
147 not callable at will and are always thrown away after the eval"" is done
148 executing).
149
150 XSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad,
151 but that is really the callers pad (a slot of which is allocated by
152 every entersub).
153
154 The CvPADLIST AV has does not have AvREAL set, so REFCNT of component items
155 is managed "manual" (mostly in op.c) rather than normal av.c rules.
156 The items in the AV are not SVs as for a normal AV, but other AVs:
157
158 0'th Entry of the CvPADLIST is an AV which represents the "names" or rather
159 the "static type information" for lexicals.
160
161 The CvDEPTH'th entry of CvPADLIST AV is an AV which is the stack frame at that
162 depth of recursion into the CV.
163 The 0'th slot of a frame AV is an AV which is @_.
164 other entries are storage for variables and op targets.
165
166 During compilation:
167 C<PL_comppad_name> is set the the the names AV.
168 C<PL_comppad> is set the the frame AV for the frame CvDEPTH == 1.
169 C<PL_curpad> is set the body of the frame AV (i.e. AvARRAY(PL_comppad)).
170
171 Itterating over the names AV itterates over all possible pad
172 items. Pad slots that are SVs_PADTMP (targets/GVs/constants) end up having
173 &PL_sv_undef "names" (see pad_alloc()).
174
175 Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid names.
176 The rest are op targets/GVs/constants which are statically allocated
177 or resolved at compile time.  These don't have names by which they
178 can be looked up from Perl code at run time through eval"" like
179 my/our variables can be.  Since they can't be looked up by "name"
180 but only by their index allocated at compile time (which is usually
181 in PL_op->op_targ), wasting a name SV for them doesn't make sense.
182
183 The SVs in the names AV have their PV being the name of the variable.
184 NV+1..IV inclusive is a range of cop_seq numbers for which the name is valid.
185 For typed lexicals name SV is SVt_PVMG and SvSTASH points at the type.
186
187 If SvFAKE is set on the name SV then slot in the frame AVs are
188 a REFCNT'ed references to a lexical from "outside".
189
190 If the 'name' is '&' the the corresponding entry in frame AV
191 is a CV representing a possible closure.
192 (SvFAKE and name of '&' is not a meaningful combination currently but could
193 become so if C<my sub foo {}> is implemented.)
194
195 =cut
196 */
197