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 */
37 PAD ** xpadlarr_alloc; /* Pointer to beginning of array of AVs.
38 index 0 is a padnamelist * */
41 PAD * pad_1; /* this slice of PAD * array always alloced */
42 PAD * pad_2; /* maybe unalloced */
43 } * xpadlarr_dbg; /* for use with a C debugger only */
45 U32 xpadl_id; /* Semi-unique ID, shared between clones */
46 U32 xpadl_outid; /* ID of outer pad */
50 SSize_t xpadnl_fill; /* max index in use */
51 PADNAME ** xpadnl_alloc; /* pointer to beginning of array */
52 SSize_t xpadnl_max; /* max index for which array has space */
53 PADOFFSET xpadnl_max_named; /* highest index with len > 0 */
57 /* PERL_PADNAME_MINIMAL uses less memory, but on some platforms
58 PERL_PADNAME_ALIGNED may be faster, so platform-specific hints can
59 define one or the other. */
60 #if defined(PERL_PADNAME_MINIMAL) && defined (PERL_PADNAME_ALIGNED)
61 # error PERL_PADNAME_MINIMAL and PERL_PADNAME_ALIGNED are exclusive
64 #if !defined(PERL_PADNAME_MINIMAL) && !defined(PERL_PADNAME_ALIGNED)
65 # define PERL_PADNAME_MINIMAL
68 #define _PADNAME_BASE \
70 HV * xpadn_ourstash; \
72 HV * xpadn_typestash; \
86 struct padname_with_str {
87 #ifdef PERL_PADNAME_MINIMAL
90 struct padname xpadn_padname;
97 #define PADNAME_FROM_PV(s) \
98 ((PADNAME *)((s) - STRUCT_OFFSET(struct padname_with_str, xpadn_str)))
101 /* a value that PL_cop_seqmax is guaranteed never to be,
102 * flagging that a lexical is being introduced, or has not yet left scope
104 #define PERL_PADSEQ_INTRO U32_MAX
105 #define COP_SEQMAX_INC \
107 (void)(PL_cop_seqmax == PERL_PADSEQ_INTRO && PL_cop_seqmax++))
110 /* B.xs needs these for the benefit of B::Deparse */
111 /* Low range end is exclusive (valid from the cop seq after this one) */
112 /* High range end is inclusive (valid up to this cop seq) */
114 #define COP_SEQ_RANGE_LOW(pn) (pn)->xpadn_low
115 #define COP_SEQ_RANGE_HIGH(pn) (pn)->xpadn_high
116 #define PARENT_PAD_INDEX(pn) (pn)->xpadn_low
117 #define PARENT_FAKELEX_FLAGS(pn) (pn)->xpadn_high
119 /* Flags set in the SvIVX field of FAKE namesvs */
121 #define PAD_FAKELEX_ANON 1 /* the lex is declared in an ANON, or ... */
122 #define PAD_FAKELEX_MULTI 2 /* the lex can be instantiated multiple times */
124 /* flags for the pad_new() function */
126 #define padnew_CLONE 1 /* this pad is for a cloned CV */
127 #define padnew_SAVE 2 /* save old globals */
128 #define padnew_SAVESUB 4 /* also save extra stuff for start of sub */
130 /* values for the pad_tidy() function */
133 padtidy_SUB, /* tidy up a pad for a sub, */
134 padtidy_SUBCLONE, /* a cloned sub, */
135 padtidy_FORMAT /* or a format */
138 /* flags for pad_add_name_pvn. */
140 #define padadd_OUR 0x01 /* our declaration. */
141 #define padadd_STATE 0x02 /* state declaration. */
142 #define padadd_NO_DUP_CHECK 0x04 /* skip warning on dups. */
143 #define padadd_STALEOK 0x08 /* allow stale lexical in active
144 * sub, but only one level up */
146 /* ASSERT_CURPAD_LEGAL and ASSERT_CURPAD_ACTIVE respectively determine
147 * whether PL_comppad and PL_curpad are consistent and whether they have
150 # define pad_peg(label)
153 # define ASSERT_CURPAD_LEGAL(label) \
155 if (PL_comppad ? (AvARRAY(PL_comppad) != PL_curpad) : (PL_curpad != 0)) \
156 Perl_croak(aTHX_ "panic: illegal pad in %s: 0x%" UVxf "[0x%" UVxf "]",\
157 label, PTR2UV(PL_comppad), PTR2UV(PL_curpad));
160 # define ASSERT_CURPAD_ACTIVE(label) \
162 if (!PL_comppad || (AvARRAY(PL_comppad) != PL_curpad)) \
163 Perl_croak(aTHX_ "panic: invalid pad in %s: 0x%" UVxf "[0x%" UVxf "]",\
164 label, PTR2UV(PL_comppad), PTR2UV(PL_curpad));
166 # define ASSERT_CURPAD_LEGAL(label)
167 # define ASSERT_CURPAD_ACTIVE(label)
172 /* Note: the following three macros are actually defined in scope.h, but
173 * they are documented here for completeness, since they directly or
174 * indirectly affect pads.
176 =for apidoc m|void|SAVEPADSV |PADOFFSET po
177 Save a pad slot (used to restore after an iteration)
179 XXX DAPM it would make more sense to make the arg a PADOFFSET
180 =for apidoc m|void|SAVECLEARSV |SV **svp
181 Clear the pointed to pad value on scope exit. (i.e. the runtime action of
184 =for apidoc m|void|SAVECOMPPAD
185 save C<PL_comppad> and C<PL_curpad>
188 =for apidoc Amx|PAD **|PadlistARRAY|PADLIST padlist
189 The C array of a padlist, containing the pads. Only subscript it with
190 numbers >= 1, as the 0th entry is not guaranteed to remain usable.
192 =for apidoc Amx|SSize_t|PadlistMAX|PADLIST padlist
193 The index of the last allocated space in the padlist. Note that the last
194 pad may be in an earlier slot. Any entries following it will be C<NULL> in
197 =for apidoc Amx|PADNAMELIST *|PadlistNAMES|PADLIST padlist
198 The names associated with pad entries.
200 =for apidoc Amx|PADNAME **|PadlistNAMESARRAY|PADLIST padlist
201 The C array of pad names.
203 =for apidoc Amx|SSize_t|PadlistNAMESMAX|PADLIST padlist
204 The index of the last pad name.
206 =for apidoc Amx|U32|PadlistREFCNT|PADLIST padlist
207 The reference count of the padlist. Currently this is always 1.
209 =for apidoc Amx|PADNAME **|PadnamelistARRAY|PADNAMELIST pnl
210 The C array of pad names.
212 =for apidoc Amx|SSize_t|PadnamelistMAX|PADNAMELIST pnl
213 The index of the last pad name.
215 =for apidoc Amx|SSize_t|PadnamelistREFCNT|PADNAMELIST pnl
216 The reference count of the pad name list.
218 =for apidoc Amx|void|PadnamelistREFCNT_dec|PADNAMELIST pnl
219 Lowers the reference count of the pad name list.
221 =for apidoc Amx|SV **|PadARRAY|PAD pad
222 The C array of pad entries.
224 =for apidoc Amx|SSize_t|PadMAX|PAD pad
225 The index of the last pad entry.
227 =for apidoc Amx|char *|PadnamePV|PADNAME pn
228 The name stored in the pad name struct. This returns C<NULL> for a target
231 =for apidoc Amx|STRLEN|PadnameLEN|PADNAME pn
232 The length of the name.
234 =for apidoc Amx|bool|PadnameUTF8|PADNAME pn
235 Whether PadnamePV is in UTF-8. Currently, this is always true.
237 =for apidoc Amx|SV *|PadnameSV|PADNAME pn
238 Returns the pad name as a mortal SV.
240 =for apidoc m|bool|PadnameIsOUR|PADNAME pn
241 Whether this is an "our" variable.
243 =for apidoc m|HV *|PadnameOURSTASH
244 The stash in which this "our" variable was declared.
246 =for apidoc m|bool|PadnameOUTER|PADNAME pn
247 Whether this entry belongs to an outer pad. Entries for which this is true
248 are often referred to as 'fake'.
250 =for apidoc m|bool|PadnameIsSTATE|PADNAME pn
251 Whether this is a "state" variable.
253 =for apidoc m|HV *|PadnameTYPE|PADNAME pn
254 The stash associated with a typed lexical. This returns the C<%Foo::> hash
257 =for apidoc Amx|SSize_t|PadnameREFCNT|PADNAME pn
258 The reference count of the pad name.
260 =for apidoc Amx|void|PadnameREFCNT_dec|PADNAME pn
261 Lowers the reference count of the pad name.
264 =for apidoc m|SV *|PAD_SETSV |PADOFFSET po|SV* sv
265 Set the slot at offset C<po> in the current pad to C<sv>
267 =for apidoc m|SV *|PAD_SV |PADOFFSET po
268 Get the value at offset C<po> in the current pad
270 =for apidoc m|SV *|PAD_SVl |PADOFFSET po
271 Lightweight and lvalue version of C<PAD_SV>.
272 Get or set the value at offset C<po> in the current pad.
273 Unlike C<PAD_SV>, does not print diagnostics with -DX.
274 For internal use only.
276 =for apidoc m|SV *|PAD_BASE_SV |PADLIST padlist|PADOFFSET po
277 Get the value from slot C<po> in the base (DEPTH=1) pad of a padlist
279 =for apidoc m|void|PAD_SET_CUR |PADLIST padlist|I32 n
280 Set the current pad to be pad C<n> in the padlist, saving
281 the previous current pad. NB currently this macro expands to a string too
282 long for some compilers, so it's best to replace it with
285 PAD_SET_CUR_NOSAVE(padlist,n);
288 =for apidoc m|void|PAD_SET_CUR_NOSAVE |PADLIST padlist|I32 n
289 like PAD_SET_CUR, but without the save
291 =for apidoc m|void|PAD_SAVE_SETNULLPAD
292 Save the current pad then set it to null.
294 =for apidoc m|void|PAD_SAVE_LOCAL|PAD *opad|PAD *npad
295 Save the current pad to the local variable C<opad>, then make the
296 current pad equal to C<npad>
298 =for apidoc m|void|PAD_RESTORE_LOCAL|PAD *opad
299 Restore the old pad saved into the local variable C<opad> by C<PAD_SAVE_LOCAL()>
304 #define PadlistARRAY(pl) (pl)->xpadl_arr.xpadlarr_alloc
305 #define PadlistMAX(pl) (pl)->xpadl_max
306 #define PadlistNAMES(pl) *((PADNAMELIST **)PadlistARRAY(pl))
307 #define PadlistNAMESARRAY(pl) PadnamelistARRAY(PadlistNAMES(pl))
308 #define PadlistNAMESMAX(pl) PadnamelistMAX(PadlistNAMES(pl))
309 #define PadlistREFCNT(pl) 1 /* reserved for future use */
311 #define PadnamelistARRAY(pnl) (pnl)->xpadnl_alloc
312 #define PadnamelistMAX(pnl) (pnl)->xpadnl_fill
313 #define PadnamelistMAXNAMED(pnl) (pnl)->xpadnl_max_named
314 #define PadnamelistREFCNT(pnl) (pnl)->xpadnl_refcnt
315 #define PadnamelistREFCNT_dec(pnl) Perl_padnamelist_free(aTHX_ pnl)
317 #define PadARRAY(pad) AvARRAY(pad)
318 #define PadMAX(pad) AvFILLp(pad)
320 #define PadnamePV(pn) (pn)->xpadn_pv
321 #define PadnameLEN(pn) (pn)->xpadn_len
322 #define PadnameUTF8(pn) 1
323 #define PadnameSV(pn) \
324 newSVpvn_flags(PadnamePV(pn), PadnameLEN(pn), SVs_TEMP|SVf_UTF8)
325 #define PadnameFLAGS(pn) (pn)->xpadn_flags
326 #define PadnameIsOUR(pn) (!!(pn)->xpadn_ourstash)
327 #define PadnameOURSTASH(pn) (pn)->xpadn_ourstash
328 #define PadnameTYPE(pn) (pn)->xpadn_type_u.xpadn_typestash
329 #define PadnamePROTOCV(pn) (pn)->xpadn_type_u.xpadn_protocv
330 #define PadnameREFCNT(pn) (pn)->xpadn_refcnt
331 #define PadnameREFCNT_dec(pn) Perl_padname_free(aTHX_ pn)
332 #define PadnameOURSTASH_set(pn,s) (PadnameOURSTASH(pn) = (s))
333 #define PadnameTYPE_set(pn,s) (PadnameTYPE(pn) = (s))
334 #define PadnameOUTER(pn) (PadnameFLAGS(pn) & PADNAMEt_OUTER)
335 #define PadnameIsSTATE(pn) (PadnameFLAGS(pn) & PADNAMEt_STATE)
336 #define PadnameLVALUE(pn) (PadnameFLAGS(pn) & PADNAMEt_LVALUE)
338 #define PadnameLVALUE_on(pn) (PadnameFLAGS(pn) |= PADNAMEt_LVALUE)
339 #define PadnameIsSTATE_on(pn) (PadnameFLAGS(pn) |= PADNAMEt_STATE)
341 #define PADNAMEt_OUTER 1 /* outer lexical var */
342 #define PADNAMEt_STATE 2 /* state var */
343 #define PADNAMEt_LVALUE 4 /* used as lvalue */
344 #define PADNAMEt_TYPED 8 /* for B; unused by core */
345 #define PADNAMEt_OUR 16 /* for B; unused by core */
347 /* backward compatibility */
348 #define SvPAD_STATE PadnameIsSTATE
349 #define SvPAD_TYPED(pn) (!!PadnameTYPE(pn))
350 #define SvPAD_OUR(pn) (!!PadnameOURSTASH(pn))
351 #define SvPAD_STATE_on PadnameIsSTATE_on
352 #define SvPAD_TYPED_on(pn) (PadnameFLAGS(pn) |= PADNAMEt_TYPED)
353 #define SvPAD_OUR_on(pn) (PadnameFLAGS(pn) |= PADNAMEt_OUR)
354 #define SvOURSTASH PadnameOURSTASH
355 #define SvOURSTASH_set PadnameOURSTASH_set
356 #define SVpad_STATE PADNAMEt_STATE
357 #define SVpad_TYPED PADNAMEt_TYPED
358 #define SVpad_OUR PADNAMEt_OUR
361 # define PAD_SV(po) pad_sv(po)
362 # define PAD_SETSV(po,sv) pad_setsv(po,sv)
364 # define PAD_SV(po) (PL_curpad[po])
365 # define PAD_SETSV(po,sv) PL_curpad[po] = (sv)
368 #define PAD_SVl(po) (PL_curpad[po])
370 #define PAD_BASE_SV(padlist, po) \
371 (PadlistARRAY(padlist)[1]) \
372 ? AvARRAY(MUTABLE_AV((PadlistARRAY(padlist)[1])))[po] \
376 #define PAD_SET_CUR_NOSAVE(padlist,nth) \
377 PL_comppad = (PAD*) (PadlistARRAY(padlist)[nth]); \
378 PL_curpad = AvARRAY(PL_comppad); \
379 DEBUG_Xv(PerlIO_printf(Perl_debug_log, \
380 "Pad 0x%" UVxf "[0x%" UVxf "] set_cur depth=%d\n", \
381 PTR2UV(PL_comppad), PTR2UV(PL_curpad), (int)(nth)));
384 #define PAD_SET_CUR(padlist,nth) \
386 PAD_SET_CUR_NOSAVE(padlist,nth);
389 #define PAD_SAVE_SETNULLPAD() SAVECOMPPAD(); \
390 PL_comppad = NULL; PL_curpad = NULL; \
391 DEBUG_Xv(PerlIO_printf(Perl_debug_log, "Pad set_null\n"));
393 #define PAD_SAVE_LOCAL(opad,npad) \
395 PL_comppad = (npad); \
396 PL_curpad = PL_comppad ? AvARRAY(PL_comppad) : NULL; \
397 DEBUG_Xv(PerlIO_printf(Perl_debug_log, \
398 "Pad 0x%" UVxf "[0x%" UVxf "] save_local\n", \
399 PTR2UV(PL_comppad), PTR2UV(PL_curpad)));
401 #define PAD_RESTORE_LOCAL(opad) \
402 assert(!opad || !SvIS_FREED(opad)); \
404 PL_curpad = PL_comppad ? AvARRAY(PL_comppad) : NULL; \
405 DEBUG_Xv(PerlIO_printf(Perl_debug_log, \
406 "Pad 0x%" UVxf "[0x%" UVxf "] restore_local\n", \
407 PTR2UV(PL_comppad), PTR2UV(PL_curpad)));
411 =for apidoc m|void|CX_CURPAD_SAVE|struct context
412 Save the current pad in the given context block structure.
414 =for apidoc m|SV *|CX_CURPAD_SV|struct context|PADOFFSET po
415 Access the SV at offset C<po> in the saved current pad in the given
416 context block structure (can be used as an lvalue).
421 #define CX_CURPAD_SAVE(block) (block).oldcomppad = PL_comppad
422 #define CX_CURPAD_SV(block,po) (AvARRAY(MUTABLE_AV(((block).oldcomppad)))[po])
426 =for apidoc m|U32|PAD_COMPNAME_FLAGS|PADOFFSET po
427 Return the flags for the current compiling pad name
428 at offset C<po>. Assumes a valid slot entry.
430 =for apidoc m|char *|PAD_COMPNAME_PV|PADOFFSET po
431 Return the name of the current compiling pad name
432 at offset C<po>. Assumes a valid slot entry.
434 =for apidoc m|HV *|PAD_COMPNAME_TYPE|PADOFFSET po
435 Return the type (stash) of the current compiling pad name at offset
436 C<po>. Must be a valid name. Returns null if not typed.
438 =for apidoc m|HV *|PAD_COMPNAME_OURSTASH|PADOFFSET po
439 Return the stash associated with an C<our> variable.
440 Assumes the slot entry is a valid C<our> lexical.
442 =for apidoc m|STRLEN|PAD_COMPNAME_GEN|PADOFFSET po
443 The generation number of the name at offset C<po> in the current
444 compiling pad (lvalue).
446 =for apidoc m|STRLEN|PAD_COMPNAME_GEN_set|PADOFFSET po|int gen
447 Sets the generation number of the name at offset C<po> in the current
448 ling pad (lvalue) to C<gen>.
453 #define PAD_COMPNAME(po) PAD_COMPNAME_SV(po)
454 #define PAD_COMPNAME_SV(po) (PadnamelistARRAY(PL_comppad_name)[(po)])
455 #define PAD_COMPNAME_FLAGS(po) PadnameFLAGS(PAD_COMPNAME(po))
456 #define PAD_COMPNAME_FLAGS_isOUR(po) SvPAD_OUR(PAD_COMPNAME_SV(po))
457 #define PAD_COMPNAME_PV(po) PadnamePV(PAD_COMPNAME(po))
459 #define PAD_COMPNAME_TYPE(po) PadnameTYPE(PAD_COMPNAME(po))
461 #define PAD_COMPNAME_OURSTASH(po) \
462 (SvOURSTASH(PAD_COMPNAME_SV(po)))
464 #define PAD_COMPNAME_GEN(po) \
465 ((STRLEN)PadnamelistARRAY(PL_comppad_name)[po]->xpadn_gen)
467 #define PAD_COMPNAME_GEN_set(po, gen) \
468 (PadnamelistARRAY(PL_comppad_name)[po]->xpadn_gen = (gen))
472 =for apidoc m|void|PAD_CLONE_VARS|PerlInterpreter *proto_perl|CLONE_PARAMS* param
473 Clone the state variables associated with running and compiling pads.
478 /* NB - we set PL_comppad to null unless it points at a value that
479 * has already been dup'ed, ie it points to part of an active padlist.
480 * Otherwise PL_comppad ends up being a leaked scalar in code like
482 * threads->create(sub { threads->create(sub {...} ) } );
483 * where the second thread dups the outer sub's comppad but not the
484 * sub's CV or padlist. */
486 #define PAD_CLONE_VARS(proto_perl, param) \
487 PL_comppad = av_dup(proto_perl->Icomppad, param); \
488 PL_curpad = PL_comppad ? AvARRAY(PL_comppad) : NULL; \
490 padnamelist_dup(proto_perl->Icomppad_name, param); \
491 PL_comppad_name_fill = proto_perl->Icomppad_name_fill; \
492 PL_comppad_name_floor = proto_perl->Icomppad_name_floor; \
493 PL_min_intro_pending = proto_perl->Imin_intro_pending; \
494 PL_max_intro_pending = proto_perl->Imax_intro_pending; \
495 PL_padix = proto_perl->Ipadix; \
496 PL_padix_floor = proto_perl->Ipadix_floor; \
497 PL_pad_reset_pending = proto_perl->Ipad_reset_pending; \
498 PL_cop_seqmax = proto_perl->Icop_seqmax;
501 =for apidoc Am|PADOFFSET|pad_add_name_pvs|const char *name|U32 flags|HV *typestash|HV *ourstash
503 Exactly like L</pad_add_name_pvn>, but takes a literal string instead
504 of a string/length pair.
509 #define pad_add_name_pvs(name,flags,typestash,ourstash) \
510 Perl_pad_add_name_pvn(aTHX_ STR_WITH_LEN(name), flags, typestash, ourstash)
513 =for apidoc Am|PADOFFSET|pad_findmy_pvs|const char *name|U32 flags
515 Exactly like L</pad_findmy_pvn>, but takes a literal string instead
516 of a string/length pair.
521 #define pad_findmy_pvs(name,flags) \
522 Perl_pad_findmy_pvn(aTHX_ STR_WITH_LEN(name), flags)
525 * ex: set ts=8 sts=4 sw=4 et: