3 * Copyright (C) 2002, 2003, 2005, 2006, 2007, 2008,
4 * 2009, 2010, 2011 by Larry Wall and others
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.
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.
15 =head1 Pad Data Structures
19 /* offsets within a pad */
22 typedef U32TYPE PADOFFSET;
25 typedef U64TYPE PADOFFSET;
28 #define NOT_IN_PAD ((PADOFFSET) -1)
30 /* B.xs expects the first members of these two structs to line up
31 (xpadl_max with xpadnl_fill).
35 SSize_t xpadl_max; /* max index for which array has space */
36 PAD ** xpadl_alloc; /* pointer to beginning of array of AVs */
37 PADNAMELIST*xpadl_outid; /* Padnamelist of outer pad; used as ID */
41 SSize_t xpadnl_fill; /* max index in use */
42 PADNAME ** xpadnl_alloc; /* pointer to beginning of array */
43 SSize_t xpadnl_max; /* max index for which array has space */
44 PADOFFSET xpadnl_max_named; /* highest index with len > 0 */
49 /* a value that PL_cop_seqmax is guaranteed never to be,
50 * flagging that a lexical is being introduced, or has not yet left scope
52 #define PERL_PADSEQ_INTRO U32_MAX
53 #define COP_SEQMAX_INC \
55 (void)(PL_cop_seqmax == PERL_PADSEQ_INTRO && PL_cop_seqmax++))
58 /* B.xs needs these for the benefit of B::Deparse */
59 /* Low range end is exclusive (valid from the cop seq after this one) */
60 /* High range end is inclusive (valid up to this cop seq) */
62 #if defined (DEBUGGING) && defined(__GNUC__) && !defined(PERL_GCC_BRACE_GROUPS_FORBIDDEN)
63 # define COP_SEQ_RANGE_LOW(sv) \
64 (({ const SV *const _sv_cop_seq_range_low = (const SV *) (sv); \
65 assert(SvTYPE(_sv_cop_seq_range_low) == SVt_NV \
66 || SvTYPE(_sv_cop_seq_range_low) >= SVt_PVNV); \
67 assert(SvTYPE(_sv_cop_seq_range_low) != SVt_PVAV); \
68 assert(SvTYPE(_sv_cop_seq_range_low) != SVt_PVHV); \
69 assert(SvTYPE(_sv_cop_seq_range_low) != SVt_PVCV); \
70 assert(SvTYPE(_sv_cop_seq_range_low) != SVt_PVFM); \
71 assert(!isGV_with_GP(_sv_cop_seq_range_low)); \
72 ((XPVNV*) MUTABLE_PTR(SvANY(_sv_cop_seq_range_low)))->xnv_u.xpad_cop_seq.xlow; \
74 # define COP_SEQ_RANGE_HIGH(sv) \
75 (({ const SV *const _sv_cop_seq_range_high = (const SV *) (sv); \
76 assert(SvTYPE(_sv_cop_seq_range_high) == SVt_NV \
77 || SvTYPE(_sv_cop_seq_range_high) >= SVt_PVNV); \
78 assert(SvTYPE(_sv_cop_seq_range_high) != SVt_PVAV); \
79 assert(SvTYPE(_sv_cop_seq_range_high) != SVt_PVHV); \
80 assert(SvTYPE(_sv_cop_seq_range_high) != SVt_PVCV); \
81 assert(SvTYPE(_sv_cop_seq_range_high) != SVt_PVFM); \
82 assert(!isGV_with_GP(_sv_cop_seq_range_high)); \
83 ((XPVNV*) MUTABLE_PTR(SvANY(_sv_cop_seq_range_high)))->xnv_u.xpad_cop_seq.xhigh; \
85 # define PARENT_PAD_INDEX(sv) \
86 (({ const SV *const _sv_parent_pad_index = (const SV *) (sv); \
87 assert(SvTYPE(_sv_parent_pad_index) == SVt_NV \
88 || SvTYPE(_sv_parent_pad_index) >= SVt_PVNV); \
89 assert(SvTYPE(_sv_parent_pad_index) != SVt_PVAV); \
90 assert(SvTYPE(_sv_parent_pad_index) != SVt_PVHV); \
91 assert(SvTYPE(_sv_parent_pad_index) != SVt_PVCV); \
92 assert(SvTYPE(_sv_parent_pad_index) != SVt_PVFM); \
93 assert(!isGV_with_GP(_sv_parent_pad_index)); \
94 ((XPVNV*) MUTABLE_PTR(SvANY(_sv_parent_pad_index)))->xnv_u.xpad_cop_seq.xlow; \
96 # define PARENT_FAKELEX_FLAGS(sv) \
97 (({ const SV *const _sv_parent_fakelex_flags = (const SV *) (sv); \
98 assert(SvTYPE(_sv_parent_fakelex_flags) == SVt_NV \
99 || SvTYPE(_sv_parent_fakelex_flags) >= SVt_PVNV); \
100 assert(SvTYPE(_sv_parent_fakelex_flags) != SVt_PVAV); \
101 assert(SvTYPE(_sv_parent_fakelex_flags) != SVt_PVHV); \
102 assert(SvTYPE(_sv_parent_fakelex_flags) != SVt_PVCV); \
103 assert(SvTYPE(_sv_parent_fakelex_flags) != SVt_PVFM); \
104 assert(!isGV_with_GP(_sv_parent_fakelex_flags)); \
105 ((XPVNV*) MUTABLE_PTR(SvANY(_sv_parent_fakelex_flags)))->xnv_u.xpad_cop_seq.xhigh; \
108 # define COP_SEQ_RANGE_LOW(sv) \
109 (0 + (((XPVNV*) SvANY(sv))->xnv_u.xpad_cop_seq.xlow))
110 # define COP_SEQ_RANGE_HIGH(sv) \
111 (0 + (((XPVNV*) SvANY(sv))->xnv_u.xpad_cop_seq.xhigh))
114 # define PARENT_PAD_INDEX(sv) \
115 (0 + (((XPVNV*) SvANY(sv))->xnv_u.xpad_cop_seq.xlow))
116 # define PARENT_FAKELEX_FLAGS(sv) \
117 (0 + (((XPVNV*) SvANY(sv))->xnv_u.xpad_cop_seq.xhigh))
120 /* Flags set in the SvIVX field of FAKE namesvs */
122 #define PAD_FAKELEX_ANON 1 /* the lex is declared in an ANON, or ... */
123 #define PAD_FAKELEX_MULTI 2 /* the lex can be instantiated multiple times */
125 /* flags for the pad_new() function */
127 #define padnew_CLONE 1 /* this pad is for a cloned CV */
128 #define padnew_SAVE 2 /* save old globals */
129 #define padnew_SAVESUB 4 /* also save extra stuff for start of sub */
131 /* values for the pad_tidy() function */
134 padtidy_SUB, /* tidy up a pad for a sub, */
135 padtidy_SUBCLONE, /* a cloned sub, */
136 padtidy_FORMAT /* or a format */
139 /* flags for pad_add_name_pvn. */
141 #define padadd_OUR 0x01 /* our declaration. */
142 #define padadd_STATE 0x02 /* state declaration. */
143 #define padadd_NO_DUP_CHECK 0x04 /* skip warning on dups. */
144 #define padadd_STALEOK 0x08 /* allow stale lexical in active
145 * sub, but only one level up */
147 /* ASSERT_CURPAD_LEGAL and ASSERT_CURPAD_ACTIVE respectively determine
148 * whether PL_comppad and PL_curpad are consistent and whether they have
151 # define pad_peg(label)
154 # define ASSERT_CURPAD_LEGAL(label) \
156 if (PL_comppad ? (AvARRAY(PL_comppad) != PL_curpad) : (PL_curpad != 0)) \
157 Perl_croak(aTHX_ "panic: illegal pad in %s: 0x%" UVxf "[0x%" UVxf "]",\
158 label, PTR2UV(PL_comppad), PTR2UV(PL_curpad));
161 # define ASSERT_CURPAD_ACTIVE(label) \
163 if (!PL_comppad || (AvARRAY(PL_comppad) != PL_curpad)) \
164 Perl_croak(aTHX_ "panic: invalid pad in %s: 0x%" UVxf "[0x%" UVxf "]",\
165 label, PTR2UV(PL_comppad), PTR2UV(PL_curpad));
167 # define ASSERT_CURPAD_LEGAL(label)
168 # define ASSERT_CURPAD_ACTIVE(label)
173 /* Note: the following three macros are actually defined in scope.h, but
174 * they are documented here for completeness, since they directly or
175 * indirectly affect pads.
177 =for apidoc m|void|SAVEPADSV |PADOFFSET po
178 Save a pad slot (used to restore after an iteration)
180 XXX DAPM it would make more sense to make the arg a PADOFFSET
181 =for apidoc m|void|SAVECLEARSV |SV **svp
182 Clear the pointed to pad value on scope exit. (i.e. the runtime action of
185 =for apidoc m|void|SAVECOMPPAD
186 save PL_comppad and PL_curpad
189 =for apidoc Amx|PAD **|PadlistARRAY|PADLIST padlist
190 The C array of a padlist, containing the pads. Only subscript it with
191 numbers >= 1, as the 0th entry is not guaranteed to remain usable.
193 =for apidoc Amx|SSize_t|PadlistMAX|PADLIST padlist
194 The index of the last allocated space in the padlist. Note that the last
195 pad may be in an earlier slot. Any entries following it will be NULL in
198 =for apidoc Amx|PADNAMELIST *|PadlistNAMES|PADLIST padlist
199 The names associated with pad entries.
201 =for apidoc Amx|PADNAME **|PadlistNAMESARRAY|PADLIST padlist
202 The C array of pad names.
204 =for apidoc Amx|SSize_t|PadlistNAMESMAX|PADLIST padlist
205 The index of the last pad name.
207 =for apidoc Amx|U32|PadlistREFCNT|PADLIST padlist
208 The reference count of the padlist. Currently this is always 1.
210 =for apidoc Amx|PADNAME **|PadnamelistARRAY|PADNAMELIST pnl
211 The C array of pad names.
213 =for apidoc Amx|SSize_t|PadnamelistMAX|PADNAMELIST pnl
214 The index of the last pad name.
216 =for apidoc Amx|SSize_t|PadnamelistREFCNT|PADNAMELIST pnl
217 The reference count of the pad name list.
219 =for apidoc Amx|void|PadnamelistREFCNT_dec|PADNAMELIST pnl
220 Lowers the reference count of the pad name list.
222 =for apidoc Amx|SV **|PadARRAY|PAD pad
223 The C array of pad entries.
225 =for apidoc Amx|SSize_t|PadMAX|PAD pad
226 The index of the last pad entry.
228 =for apidoc Amx|char *|PadnamePV|PADNAME pn
229 The name stored in the pad name struct. This returns NULL for a target
232 =for apidoc Amx|STRLEN|PadnameLEN|PADNAME pn
233 The length of the name.
235 =for apidoc Amx|bool|PadnameUTF8|PADNAME pn
236 Whether PadnamePV is in UTF8. Currently, this is always true.
238 =for apidoc Amx|SV *|PadnameSV|PADNAME pn
239 Returns the pad name as an SV. This is currently just C<pn>. It will
240 begin returning a new mortal SV if pad names ever stop being SVs.
242 =for apidoc m|bool|PadnameIsOUR|PADNAME pn
243 Whether this is an "our" variable.
245 =for apidoc m|HV *|PadnameOURSTASH
246 The stash in which this "our" variable was declared.
248 =for apidoc m|bool|PadnameOUTER|PADNAME pn
249 Whether this entry belongs to an outer pad. Entries for which this is true
250 are often referred to as 'fake'.
252 =for apidoc m|bool|PadnameIsSTATE|PADNAME pn
253 Whether this is a "state" variable.
255 =for apidoc m|HV *|PadnameTYPE|PADNAME pn
256 The stash associated with a typed lexical. This returns the %Foo:: hash
260 =for apidoc m|SV *|PAD_SETSV |PADOFFSET po|SV* sv
261 Set the slot at offset C<po> in the current pad to C<sv>
263 =for apidoc m|SV *|PAD_SV |PADOFFSET po
264 Get the value at offset C<po> in the current pad
266 =for apidoc m|SV *|PAD_SVl |PADOFFSET po
267 Lightweight and lvalue version of C<PAD_SV>.
268 Get or set the value at offset C<po> in the current pad.
269 Unlike C<PAD_SV>, does not print diagnostics with -DX.
270 For internal use only.
272 =for apidoc m|SV *|PAD_BASE_SV |PADLIST padlist|PADOFFSET po
273 Get the value from slot C<po> in the base (DEPTH=1) pad of a padlist
275 =for apidoc m|void|PAD_SET_CUR |PADLIST padlist|I32 n
276 Set the current pad to be pad C<n> in the padlist, saving
277 the previous current pad. NB currently this macro expands to a string too
278 long for some compilers, so it's best to replace it with
281 PAD_SET_CUR_NOSAVE(padlist,n);
284 =for apidoc m|void|PAD_SET_CUR_NOSAVE |PADLIST padlist|I32 n
285 like PAD_SET_CUR, but without the save
287 =for apidoc m|void|PAD_SAVE_SETNULLPAD
288 Save the current pad then set it to null.
290 =for apidoc m|void|PAD_SAVE_LOCAL|PAD *opad|PAD *npad
291 Save the current pad to the local variable opad, then make the
292 current pad equal to npad
294 =for apidoc m|void|PAD_RESTORE_LOCAL|PAD *opad
295 Restore the old pad saved into the local variable opad by PAD_SAVE_LOCAL()
300 #define PadlistARRAY(pl) (pl)->xpadl_alloc
301 #define PadlistMAX(pl) (pl)->xpadl_max
302 #define PadlistNAMES(pl) ((PADNAMELIST *)*PadlistARRAY(pl))
303 #define PadlistNAMESARRAY(pl) PadnamelistARRAY(PadlistNAMES(pl))
304 #define PadlistNAMESMAX(pl) PadnamelistMAX(PadlistNAMES(pl))
305 #define PadlistREFCNT(pl) 1 /* reserved for future use */
307 #define PadnamelistARRAY(pnl) (pnl)->xpadnl_alloc
308 #define PadnamelistMAX(pnl) (pnl)->xpadnl_fill
309 #define PadnamelistMAXNAMED(pnl) (pnl)->xpadnl_max_named
310 #define PadnamelistREFCNT(pnl) (pnl)->xpadnl_refcnt
311 #define PadnamelistREFCNT_dec(pnl) Perl_padnamelist_free(aTHX_ pnl)
313 #define PadARRAY(pad) AvARRAY(pad)
314 #define PadMAX(pad) AvFILLp(pad)
316 #define PadnamePV(pn) (SvPOKp(pn) ? SvPVX_const(pn) : NULL)
317 #define PadnameLEN(pn) ((SV*)(pn) == &PL_sv_undef ? 0 : SvCUR(pn))
318 #define PadnameUTF8(pn) (assert_(SvUTF8(pn)) 1)
319 #define PadnameSV(pn) pn
320 #define PadnameIsOUR(pn) !!SvPAD_OUR(pn)
321 #define PadnameOURSTASH(pn) SvOURSTASH(pn)
322 #define PadnameOUTER(pn) !!SvFAKE(pn)
323 #define PadnameIsSTATE(pn) !!SvPAD_STATE(pn)
324 #define PadnameTYPE(pn) (SvPAD_TYPED(pn) ? SvSTASH(pn) : NULL)
325 #define PadnameLVALUE(pn) \
326 ((SvFLAGS(pn) & (SVpad_NAME|SVpad_LVALUE))==(SVpad_NAME|SVpad_LVALUE))
328 #define PadnameLVALUE_on(pn) (SvFLAGS(pn) |= SVpad_NAME|SVpad_LVALUE)
331 # define PAD_SV(po) pad_sv(po)
332 # define PAD_SETSV(po,sv) pad_setsv(po,sv)
334 # define PAD_SV(po) (PL_curpad[po])
335 # define PAD_SETSV(po,sv) PL_curpad[po] = (sv)
338 #define PAD_SVl(po) (PL_curpad[po])
340 #define PAD_BASE_SV(padlist, po) \
341 (PadlistARRAY(padlist)[1]) \
342 ? AvARRAY(MUTABLE_AV((PadlistARRAY(padlist)[1])))[po] \
346 #define PAD_SET_CUR_NOSAVE(padlist,nth) \
347 PL_comppad = (PAD*) (PadlistARRAY(padlist)[nth]); \
348 PL_curpad = AvARRAY(PL_comppad); \
349 DEBUG_Xv(PerlIO_printf(Perl_debug_log, \
350 "Pad 0x%" UVxf "[0x%" UVxf "] set_cur depth=%d\n", \
351 PTR2UV(PL_comppad), PTR2UV(PL_curpad), (int)(nth)));
354 #define PAD_SET_CUR(padlist,nth) \
356 PAD_SET_CUR_NOSAVE(padlist,nth);
359 #define PAD_SAVE_SETNULLPAD() SAVECOMPPAD(); \
360 PL_comppad = NULL; PL_curpad = NULL; \
361 DEBUG_Xv(PerlIO_printf(Perl_debug_log, "Pad set_null\n"));
363 #define PAD_SAVE_LOCAL(opad,npad) \
365 PL_comppad = (npad); \
366 PL_curpad = PL_comppad ? AvARRAY(PL_comppad) : NULL; \
367 DEBUG_Xv(PerlIO_printf(Perl_debug_log, \
368 "Pad 0x%" UVxf "[0x%" UVxf "] save_local\n", \
369 PTR2UV(PL_comppad), PTR2UV(PL_curpad)));
371 #define PAD_RESTORE_LOCAL(opad) \
372 assert(!opad || !SvIS_FREED(opad)); \
374 PL_curpad = PL_comppad ? AvARRAY(PL_comppad) : NULL; \
375 DEBUG_Xv(PerlIO_printf(Perl_debug_log, \
376 "Pad 0x%" UVxf "[0x%" UVxf "] restore_local\n", \
377 PTR2UV(PL_comppad), PTR2UV(PL_curpad)));
381 =for apidoc m|void|CX_CURPAD_SAVE|struct context
382 Save the current pad in the given context block structure.
384 =for apidoc m|SV *|CX_CURPAD_SV|struct context|PADOFFSET po
385 Access the SV at offset po in the saved current pad in the given
386 context block structure (can be used as an lvalue).
391 #define CX_CURPAD_SAVE(block) (block).oldcomppad = PL_comppad
392 #define CX_CURPAD_SV(block,po) (AvARRAY(MUTABLE_AV(((block).oldcomppad)))[po])
396 =for apidoc m|U32|PAD_COMPNAME_FLAGS|PADOFFSET po
397 Return the flags for the current compiling pad name
398 at offset C<po>. Assumes a valid slot entry.
400 =for apidoc m|char *|PAD_COMPNAME_PV|PADOFFSET po
401 Return the name of the current compiling pad name
402 at offset C<po>. Assumes a valid slot entry.
404 =for apidoc m|HV *|PAD_COMPNAME_TYPE|PADOFFSET po
405 Return the type (stash) of the current compiling pad name at offset
406 C<po>. Must be a valid name. Returns null if not typed.
408 =for apidoc m|HV *|PAD_COMPNAME_OURSTASH|PADOFFSET po
409 Return the stash associated with an C<our> variable.
410 Assumes the slot entry is a valid C<our> lexical.
412 =for apidoc m|STRLEN|PAD_COMPNAME_GEN|PADOFFSET po
413 The generation number of the name at offset C<po> in the current
414 compiling pad (lvalue). Note that C<SvUVX> is hijacked for this purpose.
416 =for apidoc m|STRLEN|PAD_COMPNAME_GEN_set|PADOFFSET po|int gen
417 Sets the generation number of the name at offset C<po> in the current
418 ling pad (lvalue) to C<gen>. Note that C<SvUV_set> is hijacked for this purpose.
424 #define PAD_COMPNAME(po) PAD_COMPNAME_SV(po)
425 #define PAD_COMPNAME_SV(po) (PadnamelistARRAY(PL_comppad_name)[(po)])
426 #define PAD_COMPNAME_FLAGS(po) SvFLAGS(PAD_COMPNAME_SV(po))
427 #define PAD_COMPNAME_FLAGS_isOUR(po) SvPAD_OUR(PAD_COMPNAME_SV(po))
428 #define PAD_COMPNAME_PV(po) PadnamePV(PAD_COMPNAME(po))
430 #define PAD_COMPNAME_TYPE(po) PadnameTYPE(PAD_COMPNAME(po))
432 #define PAD_COMPNAME_OURSTASH(po) \
433 (SvOURSTASH(PAD_COMPNAME_SV(po)))
435 #define PAD_COMPNAME_GEN(po) \
436 ((STRLEN)SvUVX(PadnamelistARRAY(PL_comppad_name)[po]))
438 #define PAD_COMPNAME_GEN_set(po, gen) \
439 SvUV_set(PadnamelistARRAY(PL_comppad_name)[po], (UV)(gen))
443 =for apidoc m|void|PAD_CLONE_VARS|PerlInterpreter *proto_perl|CLONE_PARAMS* param
444 Clone the state variables associated with running and compiling pads.
449 /* NB - we set PL_comppad to null unless it points at a value that
450 * has already been dup'ed, ie it points to part of an active padlist.
451 * Otherwise PL_comppad ends up being a leaked scalar in code like
453 * threads->create(sub { threads->create(sub {...} ) } );
454 * where the second thread dups the outer sub's comppad but not the
455 * sub's CV or padlist. */
457 #define PAD_CLONE_VARS(proto_perl, param) \
458 PL_comppad = av_dup(proto_perl->Icomppad, param); \
459 PL_curpad = PL_comppad ? AvARRAY(PL_comppad) : NULL; \
461 padnamelist_dup(proto_perl->Icomppad_name, param); \
462 PL_comppad_name_fill = proto_perl->Icomppad_name_fill; \
463 PL_comppad_name_floor = proto_perl->Icomppad_name_floor; \
464 PL_min_intro_pending = proto_perl->Imin_intro_pending; \
465 PL_max_intro_pending = proto_perl->Imax_intro_pending; \
466 PL_padix = proto_perl->Ipadix; \
467 PL_padix_floor = proto_perl->Ipadix_floor; \
468 PL_pad_reset_pending = proto_perl->Ipad_reset_pending; \
469 PL_cop_seqmax = proto_perl->Icop_seqmax;
472 =for apidoc Am|PADOFFSET|pad_add_name_pvs|const char *name|U32 flags|HV *typestash|HV *ourstash
474 Exactly like L</pad_add_name_pvn>, but takes a literal string instead
475 of a string/length pair.
480 #define pad_add_name_pvs(name,flags,typestash,ourstash) \
481 Perl_pad_add_name_pvn(aTHX_ STR_WITH_LEN(name), flags, typestash, ourstash)
484 =for apidoc Am|PADOFFSET|pad_findmy_pvs|const char *name|U32 flags
486 Exactly like L</pad_findmy_pvn>, but takes a literal string instead
487 of a string/length pair.
492 #define pad_findmy_pvs(name,flags) \
493 Perl_pad_findmy_pvn(aTHX_ STR_WITH_LEN(name), flags)
497 * c-indentation-style: bsd
499 * indent-tabs-mode: nil
502 * ex: set ts=8 sts=4 sw=4 et: