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