Added 5.21.5 release to perlhist
[perl.git] / pad.h
1 /*    pad.h
2  *
3  *    Copyright (C) 2002, 2003, 2005, 2006, 2007, 2008,
4  *    2009, 2010, 2011 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  * This file defines the types and macros associated with the API for
10  * manipulating scratchpads, which are used by perl to store lexical
11  * variables, op targets and constants.
12  */
13
14 /*
15 =head1 Pad Data Structures
16 */
17
18
19 /* offsets within a pad */
20
21 #if PTRSIZE == 4
22 typedef U32TYPE PADOFFSET;
23 #else
24 #   if PTRSIZE == 8
25 typedef U64TYPE PADOFFSET;
26 #   endif
27 #endif
28 #define NOT_IN_PAD ((PADOFFSET) -1)
29
30
31 struct padlist {
32     SSize_t     xpadl_max;      /* max index for which array has space */
33     PAD **      xpadl_alloc;    /* pointer to beginning of array of AVs */
34     PADNAMELIST*xpadl_outid;    /* Padnamelist of outer pad; used as ID */
35 };
36
37
38 /* a value that PL_cop_seqmax is guaranteed never to be,
39  * flagging that a lexical is being introduced, or has not yet left scope
40  */
41 #define PERL_PADSEQ_INTRO  U32_MAX
42
43
44 /* B.xs needs these for the benefit of B::Deparse */
45 /* Low range end is exclusive (valid from the cop seq after this one) */
46 /* High range end is inclusive (valid up to this cop seq) */
47
48 #if defined (DEBUGGING) && defined(__GNUC__) && !defined(PERL_GCC_BRACE_GROUPS_FORBIDDEN)
49 #  define COP_SEQ_RANGE_LOW(sv)                                         \
50         (({ const SV *const _sv_cop_seq_range_low = (const SV *) (sv);  \
51           assert(SvTYPE(_sv_cop_seq_range_low) == SVt_NV                \
52                  || SvTYPE(_sv_cop_seq_range_low) >= SVt_PVNV);         \
53           assert(SvTYPE(_sv_cop_seq_range_low) != SVt_PVAV);            \
54           assert(SvTYPE(_sv_cop_seq_range_low) != SVt_PVHV);            \
55           assert(SvTYPE(_sv_cop_seq_range_low) != SVt_PVCV);            \
56           assert(SvTYPE(_sv_cop_seq_range_low) != SVt_PVFM);            \
57           assert(!isGV_with_GP(_sv_cop_seq_range_low));                 \
58           ((XPVNV*) MUTABLE_PTR(SvANY(_sv_cop_seq_range_low)))->xnv_u.xpad_cop_seq.xlow; \
59          }))
60 #  define COP_SEQ_RANGE_HIGH(sv)                                        \
61         (({ const SV *const _sv_cop_seq_range_high = (const SV *) (sv); \
62           assert(SvTYPE(_sv_cop_seq_range_high) == SVt_NV               \
63                  || SvTYPE(_sv_cop_seq_range_high) >= SVt_PVNV);        \
64           assert(SvTYPE(_sv_cop_seq_range_high) != SVt_PVAV);           \
65           assert(SvTYPE(_sv_cop_seq_range_high) != SVt_PVHV);           \
66           assert(SvTYPE(_sv_cop_seq_range_high) != SVt_PVCV);           \
67           assert(SvTYPE(_sv_cop_seq_range_high) != SVt_PVFM);           \
68           assert(!isGV_with_GP(_sv_cop_seq_range_high));                \
69           ((XPVNV*) MUTABLE_PTR(SvANY(_sv_cop_seq_range_high)))->xnv_u.xpad_cop_seq.xhigh; \
70          }))
71 #  define PARENT_PAD_INDEX(sv)                                          \
72         (({ const SV *const _sv_parent_pad_index = (const SV *) (sv);   \
73           assert(SvTYPE(_sv_parent_pad_index) == SVt_NV                 \
74                  || SvTYPE(_sv_parent_pad_index) >= SVt_PVNV);          \
75           assert(SvTYPE(_sv_parent_pad_index) != SVt_PVAV);             \
76           assert(SvTYPE(_sv_parent_pad_index) != SVt_PVHV);             \
77           assert(SvTYPE(_sv_parent_pad_index) != SVt_PVCV);             \
78           assert(SvTYPE(_sv_parent_pad_index) != SVt_PVFM);             \
79           assert(!isGV_with_GP(_sv_parent_pad_index));                  \
80           ((XPVNV*) MUTABLE_PTR(SvANY(_sv_parent_pad_index)))->xnv_u.xpad_cop_seq.xlow; \
81          }))
82 #  define PARENT_FAKELEX_FLAGS(sv)                                      \
83         (({ const SV *const _sv_parent_fakelex_flags = (const SV *) (sv); \
84           assert(SvTYPE(_sv_parent_fakelex_flags) == SVt_NV             \
85                  || SvTYPE(_sv_parent_fakelex_flags) >= SVt_PVNV);      \
86           assert(SvTYPE(_sv_parent_fakelex_flags) != SVt_PVAV);         \
87           assert(SvTYPE(_sv_parent_fakelex_flags) != SVt_PVHV);         \
88           assert(SvTYPE(_sv_parent_fakelex_flags) != SVt_PVCV);         \
89           assert(SvTYPE(_sv_parent_fakelex_flags) != SVt_PVFM);         \
90           assert(!isGV_with_GP(_sv_parent_fakelex_flags));              \
91           ((XPVNV*) MUTABLE_PTR(SvANY(_sv_parent_fakelex_flags)))->xnv_u.xpad_cop_seq.xhigh; \
92          }))
93 #else
94 #  define COP_SEQ_RANGE_LOW(sv)         \
95         (0 + (((XPVNV*) SvANY(sv))->xnv_u.xpad_cop_seq.xlow))
96 #  define COP_SEQ_RANGE_HIGH(sv)        \
97         (0 + (((XPVNV*) SvANY(sv))->xnv_u.xpad_cop_seq.xhigh))
98
99
100 #  define PARENT_PAD_INDEX(sv)          \
101         (0 + (((XPVNV*) SvANY(sv))->xnv_u.xpad_cop_seq.xlow))
102 #  define PARENT_FAKELEX_FLAGS(sv)      \
103         (0 + (((XPVNV*) SvANY(sv))->xnv_u.xpad_cop_seq.xhigh))
104 #endif
105
106 /* Flags set in the SvIVX field of FAKE namesvs */
107
108 #define PAD_FAKELEX_ANON   1 /* the lex is declared in an ANON, or ... */
109 #define PAD_FAKELEX_MULTI  2 /* the lex can be instantiated multiple times */
110
111 /* flags for the pad_new() function */
112
113 #define padnew_CLONE    1       /* this pad is for a cloned CV */
114 #define padnew_SAVE     2       /* save old globals */
115 #define padnew_SAVESUB  4       /* also save extra stuff for start of sub */
116
117 /* values for the pad_tidy() function */
118
119 typedef enum {
120         padtidy_SUB,            /* tidy up a pad for a sub, */
121         padtidy_SUBCLONE,       /* a cloned sub, */
122         padtidy_FORMAT          /* or a format */
123 } padtidy_type;
124
125 /* flags for pad_add_name_pvn. */
126
127 #define padadd_OUR              0x01       /* our declaration. */
128 #define padadd_STATE            0x02       /* state declaration. */
129 #define padadd_NO_DUP_CHECK     0x04       /* skip warning on dups. */
130 #define padadd_STALEOK          0x08       /* allow stale lexical in active
131                                             * sub, but only one level up */
132 #define padadd_UTF8_NAME        SVf_UTF8   /* name is UTF-8 encoded. */
133
134 /* ASSERT_CURPAD_LEGAL and ASSERT_CURPAD_ACTIVE respectively determine
135  * whether PL_comppad and PL_curpad are consistent and whether they have
136  * active values */
137
138 #  define pad_peg(label)
139
140 #ifdef DEBUGGING
141 #  define ASSERT_CURPAD_LEGAL(label) \
142     pad_peg(label); \
143     if (PL_comppad ? (AvARRAY(PL_comppad) != PL_curpad) : (PL_curpad != 0))  \
144         Perl_croak(aTHX_ "panic: illegal pad in %s: 0x%" UVxf "[0x%" UVxf "]",\
145             label, PTR2UV(PL_comppad), PTR2UV(PL_curpad));
146
147
148 #  define ASSERT_CURPAD_ACTIVE(label) \
149     pad_peg(label); \
150     if (!PL_comppad || (AvARRAY(PL_comppad) != PL_curpad))                \
151         Perl_croak(aTHX_ "panic: invalid pad in %s: 0x%" UVxf "[0x%" UVxf "]",\
152             label, PTR2UV(PL_comppad), PTR2UV(PL_curpad));
153 #else
154 #  define ASSERT_CURPAD_LEGAL(label)
155 #  define ASSERT_CURPAD_ACTIVE(label)
156 #endif
157
158
159
160 /* Note: the following three macros are actually defined in scope.h, but
161  * they are documented here for completeness, since they directly or
162  * indirectly affect pads.
163
164 =for apidoc m|void|SAVEPADSV    |PADOFFSET po
165 Save a pad slot (used to restore after an iteration)
166
167 XXX DAPM it would make more sense to make the arg a PADOFFSET
168 =for apidoc m|void|SAVECLEARSV  |SV **svp
169 Clear the pointed to pad value on scope exit.  (i.e. the runtime action of
170 'my')
171
172 =for apidoc m|void|SAVECOMPPAD
173 save PL_comppad and PL_curpad
174
175
176 =for apidoc Amx|PAD **|PadlistARRAY|PADLIST padlist
177 The C array of a padlist, containing the pads.  Only subscript it with
178 numbers >= 1, as the 0th entry is not guaranteed to remain usable.
179
180 =for apidoc Amx|SSize_t|PadlistMAX|PADLIST padlist
181 The index of the last allocated space in the padlist.  Note that the last
182 pad may be in an earlier slot.  Any entries following it will be NULL in
183 that case.
184
185 =for apidoc Amx|PADNAMELIST *|PadlistNAMES|PADLIST padlist
186 The names associated with pad entries.
187
188 =for apidoc Amx|PADNAME **|PadlistNAMESARRAY|PADLIST padlist
189 The C array of pad names.
190
191 =for apidoc Amx|SSize_t|PadlistNAMESMAX|PADLIST padlist
192 The index of the last pad name.
193
194 =for apidoc Amx|U32|PadlistREFCNT|PADLIST padlist
195 The reference count of the padlist.  Currently this is always 1.
196
197 =for apidoc Amx|PADNAME **|PadnamelistARRAY|PADNAMELIST pnl
198 The C array of pad names.
199
200 =for apidoc Amx|SSize_t|PadnamelistMAX|PADNAMELIST pnl
201 The index of the last pad name.
202
203 =for apidoc Amx|SV **|PadARRAY|PAD pad
204 The C array of pad entries.
205
206 =for apidoc Amx|SSize_t|PadMAX|PAD pad
207 The index of the last pad entry.
208
209 =for apidoc Amx|char *|PadnamePV|PADNAME pn     
210 The name stored in the pad name struct.  This returns NULL for a target or
211 GV slot.
212
213 =for apidoc Amx|STRLEN|PadnameLEN|PADNAME pn    
214 The length of the name.
215
216 =for apidoc Amx|bool|PadnameUTF8|PADNAME pn
217 Whether PadnamePV is in UTF8.
218
219 =for apidoc Amx|SV *|PadnameSV|PADNAME pn
220 Returns the pad name as an SV.  This is currently just C<pn>.  It will
221 begin returning a new mortal SV if pad names ever stop being SVs.
222
223 =for apidoc m|bool|PadnameIsOUR|PADNAME pn
224 Whether this is an "our" variable.
225
226 =for apidoc m|HV *|PadnameOURSTASH
227 The stash in which this "our" variable was declared.
228
229 =for apidoc m|bool|PadnameOUTER|PADNAME pn
230 Whether this entry belongs to an outer pad.
231
232 =for apidoc m|bool|PadnameIsSTATE|PADNAME pn
233 Whether this is a "state" variable.
234
235 =for apidoc m|HV *|PadnameTYPE|PADNAME pn
236 The stash associated with a typed lexical.  This returns the %Foo:: hash
237 for C<my Foo $bar>.
238
239
240 =for apidoc m|SV *|PAD_SETSV    |PADOFFSET po|SV* sv
241 Set the slot at offset C<po> in the current pad to C<sv>
242
243 =for apidoc m|SV *|PAD_SV       |PADOFFSET po
244 Get the value at offset C<po> in the current pad
245
246 =for apidoc m|SV *|PAD_SVl      |PADOFFSET po
247 Lightweight and lvalue version of C<PAD_SV>.
248 Get or set the value at offset C<po> in the current pad.
249 Unlike C<PAD_SV>, does not print diagnostics with -DX.
250 For internal use only.
251
252 =for apidoc m|SV *|PAD_BASE_SV  |PADLIST padlist|PADOFFSET po
253 Get the value from slot C<po> in the base (DEPTH=1) pad of a padlist
254
255 =for apidoc m|void|PAD_SET_CUR  |PADLIST padlist|I32 n
256 Set the current pad to be pad C<n> in the padlist, saving
257 the previous current pad.  NB currently this macro expands to a string too
258 long for some compilers, so it's best to replace it with
259
260     SAVECOMPPAD();
261     PAD_SET_CUR_NOSAVE(padlist,n);
262
263
264 =for apidoc m|void|PAD_SET_CUR_NOSAVE   |PADLIST padlist|I32 n
265 like PAD_SET_CUR, but without the save
266
267 =for apidoc m|void|PAD_SAVE_SETNULLPAD
268 Save the current pad then set it to null.
269
270 =for apidoc m|void|PAD_SAVE_LOCAL|PAD *opad|PAD *npad
271 Save the current pad to the local variable opad, then make the
272 current pad equal to npad
273
274 =for apidoc m|void|PAD_RESTORE_LOCAL|PAD *opad
275 Restore the old pad saved into the local variable opad by PAD_SAVE_LOCAL()
276
277 =cut
278 */
279
280 #define PadlistARRAY(pl)        (pl)->xpadl_alloc
281 #define PadlistMAX(pl)          (pl)->xpadl_max
282 #define PadlistNAMES(pl)        (*PadlistARRAY(pl))
283 #define PadlistNAMESARRAY(pl)   PadnamelistARRAY(PadlistNAMES(pl))
284 #define PadlistNAMESMAX(pl)     PadnamelistMAX(PadlistNAMES(pl))
285 #define PadlistREFCNT(pl)       1       /* reserved for future use */
286
287 #define PadnamelistARRAY(pnl)   AvARRAY(pnl)
288 #define PadnamelistMAX(pnl)     AvFILLp(pnl)
289 #define PadnamelistMAXNAMED(pnl) \
290         ((XPVAV*) SvANY(pnl))->xmg_u.xmg_hash_index
291
292 #define PadARRAY(pad)           AvARRAY(pad)
293 #define PadMAX(pad)             AvFILLp(pad)
294
295 #define PadnamePV(pn)           (SvPOKp(pn) ? SvPVX(pn) : NULL)
296 #define PadnameLEN(pn)          ((pn) == &PL_sv_undef ? 0 : SvCUR(pn))
297 #define PadnameUTF8(pn)         !!SvUTF8(pn)
298 #define PadnameSV(pn)           pn
299 #define PadnameIsOUR(pn)        !!SvPAD_OUR(pn)
300 #define PadnameOURSTASH(pn)     SvOURSTASH(pn)
301 #define PadnameOUTER(pn)        !!SvFAKE(pn)
302 #define PadnameIsSTATE(pn)      !!SvPAD_STATE(pn)
303 #define PadnameTYPE(pn)         (SvPAD_TYPED(pn) ? SvSTASH(pn) : NULL)
304
305
306 #ifdef DEBUGGING
307 #  define PAD_SV(po)       pad_sv(po)
308 #  define PAD_SETSV(po,sv) pad_setsv(po,sv)
309 #else
310 #  define PAD_SV(po)       (PL_curpad[po])
311 #  define PAD_SETSV(po,sv) PL_curpad[po] = (sv)
312 #endif
313
314 #define PAD_SVl(po)       (PL_curpad[po])
315
316 #define PAD_BASE_SV(padlist, po) \
317         (PadlistARRAY(padlist)[1])                                      \
318             ? AvARRAY(MUTABLE_AV((PadlistARRAY(padlist)[1])))[po] \
319             : NULL;
320
321
322 #define PAD_SET_CUR_NOSAVE(padlist,nth) \
323         PL_comppad = (PAD*) (PadlistARRAY(padlist)[nth]);       \
324         PL_curpad = AvARRAY(PL_comppad);                        \
325         DEBUG_Xv(PerlIO_printf(Perl_debug_log,                  \
326               "Pad 0x%" UVxf "[0x%" UVxf "] set_cur    depth=%d\n",     \
327               PTR2UV(PL_comppad), PTR2UV(PL_curpad), (int)(nth)));
328
329
330 #define PAD_SET_CUR(padlist,nth) \
331         SAVECOMPPAD();                                          \
332         PAD_SET_CUR_NOSAVE(padlist,nth);
333
334
335 #define PAD_SAVE_SETNULLPAD()   SAVECOMPPAD(); \
336         PL_comppad = NULL; PL_curpad = NULL;    \
337         DEBUG_Xv(PerlIO_printf(Perl_debug_log, "Pad set_null\n"));
338
339 #define PAD_SAVE_LOCAL(opad,npad) \
340         opad = PL_comppad;                                      \
341         PL_comppad = (npad);                                    \
342         PL_curpad =  PL_comppad ? AvARRAY(PL_comppad) : NULL;   \
343         DEBUG_Xv(PerlIO_printf(Perl_debug_log,                  \
344               "Pad 0x%" UVxf "[0x%" UVxf "] save_local\n",              \
345               PTR2UV(PL_comppad), PTR2UV(PL_curpad)));
346
347 #define PAD_RESTORE_LOCAL(opad) \
348         assert(!opad || !SvIS_FREED(opad));                                     \
349         PL_comppad = opad;                                              \
350         PL_curpad =  PL_comppad ? AvARRAY(PL_comppad) : NULL;   \
351         DEBUG_Xv(PerlIO_printf(Perl_debug_log,                  \
352               "Pad 0x%" UVxf "[0x%" UVxf "] restore_local\n",   \
353               PTR2UV(PL_comppad), PTR2UV(PL_curpad)));
354
355
356 /*
357 =for apidoc m|void|CX_CURPAD_SAVE|struct context
358 Save the current pad in the given context block structure.
359
360 =for apidoc m|SV *|CX_CURPAD_SV|struct context|PADOFFSET po
361 Access the SV at offset po in the saved current pad in the given
362 context block structure (can be used as an lvalue).
363
364 =cut
365 */
366
367 #define CX_CURPAD_SAVE(block)  (block).oldcomppad = PL_comppad
368 #define CX_CURPAD_SV(block,po) (AvARRAY(MUTABLE_AV(((block).oldcomppad)))[po])
369
370
371 /*
372 =for apidoc m|U32|PAD_COMPNAME_FLAGS|PADOFFSET po
373 Return the flags for the current compiling pad name
374 at offset C<po>.  Assumes a valid slot entry.
375
376 =for apidoc m|char *|PAD_COMPNAME_PV|PADOFFSET po
377 Return the name of the current compiling pad name
378 at offset C<po>.  Assumes a valid slot entry.
379
380 =for apidoc m|HV *|PAD_COMPNAME_TYPE|PADOFFSET po
381 Return the type (stash) of the current compiling pad name at offset
382 C<po>.  Must be a valid name.  Returns null if not typed.
383
384 =for apidoc m|HV *|PAD_COMPNAME_OURSTASH|PADOFFSET po
385 Return the stash associated with an C<our> variable.
386 Assumes the slot entry is a valid C<our> lexical.
387
388 =for apidoc m|STRLEN|PAD_COMPNAME_GEN|PADOFFSET po
389 The generation number of the name at offset C<po> in the current
390 compiling pad (lvalue).  Note that C<SvUVX> is hijacked for this purpose.
391
392 =for apidoc m|STRLEN|PAD_COMPNAME_GEN_set|PADOFFSET po|int gen
393 Sets the generation number of the name at offset C<po> in the current
394 ling pad (lvalue) to C<gen>.  Note that C<SvUV_set> is hijacked for this purpose.
395
396 =cut
397
398 */
399
400 #define PAD_COMPNAME(po)        PAD_COMPNAME_SV(po)
401 #define PAD_COMPNAME_SV(po) (AvARRAY(PL_comppad_name)[(po)])
402 #define PAD_COMPNAME_FLAGS(po) SvFLAGS(PAD_COMPNAME_SV(po))
403 #define PAD_COMPNAME_FLAGS_isOUR(po) SvPAD_OUR(PAD_COMPNAME_SV(po))
404 #define PAD_COMPNAME_PV(po) SvPV_nolen(PAD_COMPNAME_SV(po))
405
406 #define PAD_COMPNAME_TYPE(po) pad_compname_type(po)
407
408 #define PAD_COMPNAME_OURSTASH(po) \
409     (SvOURSTASH(PAD_COMPNAME_SV(po)))
410
411 #define PAD_COMPNAME_GEN(po) ((STRLEN)SvUVX(AvARRAY(PL_comppad_name)[po]))
412
413 #define PAD_COMPNAME_GEN_set(po, gen) SvUV_set(AvARRAY(PL_comppad_name)[po], (UV)(gen))
414
415
416 /*
417 =for apidoc m|void|PAD_CLONE_VARS|PerlInterpreter *proto_perl|CLONE_PARAMS* param
418 Clone the state variables associated with running and compiling pads.
419
420 =cut
421 */
422
423 /* NB - we set PL_comppad to null unless it points at a value that
424  * has already been dup'ed, ie it points to part of an active padlist.
425  * Otherwise PL_comppad ends up being a leaked scalar in code like
426  * the following:
427  *     threads->create(sub { threads->create(sub {...} ) } );
428  * where the second thread dups the outer sub's comppad but not the
429  * sub's CV or padlist. */
430
431 #define PAD_CLONE_VARS(proto_perl, param)                               \
432     PL_comppad                  = av_dup(proto_perl->Icomppad, param);  \
433     PL_curpad = PL_comppad ?  AvARRAY(PL_comppad) : NULL;               \
434     PL_comppad_name             = av_dup(proto_perl->Icomppad_name, param); \
435     PL_comppad_name_fill        = proto_perl->Icomppad_name_fill;       \
436     PL_comppad_name_floor       = proto_perl->Icomppad_name_floor;      \
437     PL_min_intro_pending        = proto_perl->Imin_intro_pending;       \
438     PL_max_intro_pending        = proto_perl->Imax_intro_pending;       \
439     PL_padix                    = proto_perl->Ipadix;                   \
440     PL_padix_floor              = proto_perl->Ipadix_floor;             \
441     PL_pad_reset_pending        = proto_perl->Ipad_reset_pending;       \
442     PL_cop_seqmax               = proto_perl->Icop_seqmax;
443
444 /*
445 =for apidoc Am|PADOFFSET|pad_add_name_pvs|const char *name|U32 flags|HV *typestash|HV *ourstash
446
447 Exactly like L</pad_add_name_pvn>, but takes a literal string instead
448 of a string/length pair.
449
450 =cut
451 */
452
453 #define pad_add_name_pvs(name,flags,typestash,ourstash) \
454     Perl_pad_add_name_pvn(aTHX_ STR_WITH_LEN(name), flags, typestash, ourstash)
455
456 /*
457 =for apidoc Am|PADOFFSET|pad_findmy_pvs|const char *name|U32 flags
458
459 Exactly like L</pad_findmy_pvn>, but takes a literal string instead
460 of a string/length pair.
461
462 =cut
463 */
464
465 #define pad_findmy_pvs(name,flags) \
466     Perl_pad_findmy_pvn(aTHX_ STR_WITH_LEN(name), flags)
467
468 /*
469  * Local variables:
470  * c-indentation-style: bsd
471  * c-basic-offset: 4
472  * indent-tabs-mode: nil
473  * End:
474  *
475  * ex: set ts=8 sts=4 sw=4 et:
476  */