This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
pad.h: Correct PadlistMAX docs
[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
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 #ifndef PERL_MAD
139 #  define pad_peg(label)
140 #endif
141
142 #ifdef DEBUGGING
143 #  define ASSERT_CURPAD_LEGAL(label) \
144     pad_peg(label); \
145     if (PL_comppad ? (AvARRAY(PL_comppad) != PL_curpad) : (PL_curpad != 0))  \
146         Perl_croak(aTHX_ "panic: illegal pad in %s: 0x%"UVxf"[0x%"UVxf"]",\
147             label, PTR2UV(PL_comppad), PTR2UV(PL_curpad));
148
149
150 #  define ASSERT_CURPAD_ACTIVE(label) \
151     pad_peg(label); \
152     if (!PL_comppad || (AvARRAY(PL_comppad) != PL_curpad))                \
153         Perl_croak(aTHX_ "panic: invalid pad in %s: 0x%"UVxf"[0x%"UVxf"]",\
154             label, PTR2UV(PL_comppad), PTR2UV(PL_curpad));
155 #else
156 #  define ASSERT_CURPAD_LEGAL(label)
157 #  define ASSERT_CURPAD_ACTIVE(label)
158 #endif
159
160
161
162 /* Note: the following three macros are actually defined in scope.h, but
163  * they are documented here for completeness, since they directly or
164  * indirectly affect pads.
165
166 =for apidoc m|void|SAVEPADSV    |PADOFFSET po
167 Save a pad slot (used to restore after an iteration)
168
169 XXX DAPM it would make more sense to make the arg a PADOFFSET
170 =for apidoc m|void|SAVECLEARSV  |SV **svp
171 Clear the pointed to pad value on scope exit. (i.e. the runtime action of 'my')
172
173 =for apidoc m|void|SAVECOMPPAD
174 save PL_comppad and PL_curpad
175
176
177 =for apidoc Amx|PAD **|PadlistARRAY|PADLIST padlist
178 The C array of a padlist, containing the pads.  Only subscript it with
179 numbers >= 1, as the 0th entry is not guaranteed to remain usable.
180
181 =for apidoc Amx|SSize_t|PadlistMAX|PADLIST padlist
182 The index of the last allocated space in the padlist.  Note that the last
183 pad may be in an earlier slot.  Any entries following it will be NULL in
184 that case.
185
186 =for apidoc Amx|PADNAMELIST *|PadlistNAMES|PADLIST padlist
187 The names associated with pad entries.
188
189 =for apidoc Amx|PADNAME **|PadlistNAMESARRAY|PADLIST padlist
190 The C array of pad names.
191
192 =for apidoc Amx|SSize_t|PadlistNAMESMAX|PADLIST padlist
193 The index of the last pad name.
194
195 =for apidoc Amx|U32|PadlistREFCNT|PADLIST padlist
196 The reference count of the padlist.  Currently this is always 1.
197
198 =for apidoc Amx|PADNAME **|PadnamelistARRAY|PADNAMELIST pnl
199 The C array of pad names.
200
201 =for apidoc Amx|SSize_t|PadnamelistMAX|PADNAMELIST pnl
202 The index of the last pad name.
203
204 =for apidoc Amx|SV **|PadARRAY|PAD pad
205 The C array of pad entries.
206
207 =for apidoc Amx|SSize_t|PadMAX|PAD pad
208 The index of the last pad entry.
209
210 =for apidoc Amx|char *|PadnamePV|PADNAME pn     
211 The name stored in the pad name struct.  This returns NULL for a target or
212 GV slot.
213
214 =for apidoc Amx|STRLEN|PadnameLEN|PADNAME pn    
215 The length of the name.
216
217 =for apidoc Amx|bool|PadnameUTF8|PADNAME pn
218 Whether PadnamePV is in UTF8.
219
220 =for apidoc Amx|SV *|PadnameSV|PADNAME pn
221 Returns the pad name as an SV.  This is currently just C<pn>.  It will
222 begin returning a new mortal SV if pad names ever stop being SVs.
223
224 =for apidoc m|bool|PadnameIsOUR|PADNAME pn
225 Whether this is an "our" variable.
226
227 =for apidoc m|HV *|PadnameOURSTASH
228 The stash in which this "our" variable was declared.
229
230 =for apidoc m|bool|PadnameOUTER|PADNAME pn
231 Whether this entry belongs to an outer pad.
232
233 =for apidoc m|bool|PadnameIsSTATE|PADNAME pn
234 Whether this is a "state" variable.
235
236 =for apidoc m|HV *|PadnameTYPE|PADNAME pn
237 The stash associated with a typed lexical.  This returns the %Foo:: hash
238 for C<my Foo $bar>.
239
240
241 =for apidoc m|SV *|PAD_SETSV    |PADOFFSET po|SV* sv
242 Set the slot at offset C<po> in the current pad to C<sv>
243
244 =for apidoc m|void|PAD_SV       |PADOFFSET po
245 Get the value at offset C<po> in the current pad
246
247 =for apidoc m|SV *|PAD_SVl      |PADOFFSET po
248 Lightweight and lvalue version of C<PAD_SV>.
249 Get or set the value at offset C<po> in the current pad.
250 Unlike C<PAD_SV>, does not print diagnostics with -DX.
251 For internal use only.
252
253 =for apidoc m|SV *|PAD_BASE_SV  |PADLIST padlist|PADOFFSET po
254 Get the value from slot C<po> in the base (DEPTH=1) pad of a padlist
255
256 =for apidoc m|void|PAD_SET_CUR  |PADLIST padlist|I32 n
257 Set the current pad to be pad C<n> in the padlist, saving
258 the previous current pad. NB currently this macro expands to a string too
259 long for some compilers, so it's best to replace it with
260
261     SAVECOMPPAD();
262     PAD_SET_CUR_NOSAVE(padlist,n);
263
264
265 =for apidoc m|void|PAD_SET_CUR_NOSAVE   |PADLIST padlist|I32 n
266 like PAD_SET_CUR, but without the save
267
268 =for apidoc m|void|PAD_SAVE_SETNULLPAD
269 Save the current pad then set it to null.
270
271 =for apidoc m|void|PAD_SAVE_LOCAL|PAD *opad|PAD *npad
272 Save the current pad to the local variable opad, then make the
273 current pad equal to npad
274
275 =for apidoc m|void|PAD_RESTORE_LOCAL|PAD *opad
276 Restore the old pad saved into the local variable opad by PAD_SAVE_LOCAL()
277
278 =cut
279 */
280
281 #define PadlistARRAY(pl)        (pl)->xpadl_alloc
282 #define PadlistMAX(pl)          (pl)->xpadl_max
283 #define PadlistNAMES(pl)        (*PadlistARRAY(pl))
284 #define PadlistNAMESARRAY(pl)   PadnamelistARRAY(PadlistNAMES(pl))
285 #define PadlistNAMESMAX(pl)     PadnamelistMAX(PadlistNAMES(pl))
286 #define PadlistREFCNT(pl)       1       /* reserved for future use */
287
288 #define PadnamelistARRAY(pnl)   AvARRAY(pnl)
289 #define PadnamelistMAX(pnl)     AvFILLp(pnl)
290 #define PadnamelistMAXNAMED(pnl) \
291         ((XPVAV*) SvANY(pnl))->xmg_u.xmg_hash_index
292
293 #define PadARRAY(pad)           AvARRAY(pad)
294 #define PadMAX(pad)             AvFILLp(pad)
295
296 #define PadnamePV(pn)           (SvPOKp(pn) ? SvPVX(pn) : NULL)
297 #define PadnameLEN(pn)          ((pn) == &PL_sv_undef ? 0 : SvCUR(pn))
298 #define PadnameUTF8(pn)         !!SvUTF8(pn)
299 #define PadnameSV(pn)           pn
300 #define PadnameIsOUR(pn)        !!SvPAD_OUR(pn)
301 #define PadnameOURSTASH(pn)     SvOURSTASH(pn)
302 #define PadnameOUTER(pn)        !!SvFAKE(pn)
303 #define PadnameIsSTATE(pn)      !!SvPAD_STATE(pn)
304 #define PadnameTYPE(pn)         (SvPAD_TYPED(pn) ? SvSTASH(pn) : NULL)
305
306
307 #ifdef DEBUGGING
308 #  define PAD_SV(po)       pad_sv(po)
309 #  define PAD_SETSV(po,sv) pad_setsv(po,sv)
310 #else
311 #  define PAD_SV(po)       (PL_curpad[po])
312 #  define PAD_SETSV(po,sv) PL_curpad[po] = (sv)
313 #endif
314
315 #define PAD_SVl(po)       (PL_curpad[po])
316
317 #define PAD_BASE_SV(padlist, po) \
318         (PadlistARRAY(padlist)[1])                                      \
319             ? AvARRAY(MUTABLE_AV((PadlistARRAY(padlist)[1])))[po] \
320             : NULL;
321
322
323 #define PAD_SET_CUR_NOSAVE(padlist,nth) \
324         PL_comppad = (PAD*) (PadlistARRAY(padlist)[nth]);       \
325         PL_curpad = AvARRAY(PL_comppad);                        \
326         DEBUG_Xv(PerlIO_printf(Perl_debug_log,                  \
327               "Pad 0x%"UVxf"[0x%"UVxf"] set_cur    depth=%d\n", \
328               PTR2UV(PL_comppad), PTR2UV(PL_curpad), (int)(nth)));
329
330
331 #define PAD_SET_CUR(padlist,nth) \
332         SAVECOMPPAD();                                          \
333         PAD_SET_CUR_NOSAVE(padlist,nth);
334
335
336 #define PAD_SAVE_SETNULLPAD()   SAVECOMPPAD(); \
337         PL_comppad = NULL; PL_curpad = NULL;    \
338         DEBUG_Xv(PerlIO_printf(Perl_debug_log, "Pad set_null\n"));
339
340 #define PAD_SAVE_LOCAL(opad,npad) \
341         opad = PL_comppad;                                      \
342         PL_comppad = (npad);                                    \
343         PL_curpad =  PL_comppad ? AvARRAY(PL_comppad) : NULL;   \
344         DEBUG_Xv(PerlIO_printf(Perl_debug_log,                  \
345               "Pad 0x%"UVxf"[0x%"UVxf"] save_local\n",          \
346               PTR2UV(PL_comppad), PTR2UV(PL_curpad)));
347
348 #define PAD_RESTORE_LOCAL(opad) \
349         assert(!opad || !SvIS_FREED(opad));                                     \
350         PL_comppad = opad;                                              \
351         PL_curpad =  PL_comppad ? AvARRAY(PL_comppad) : NULL;   \
352         DEBUG_Xv(PerlIO_printf(Perl_debug_log,                  \
353               "Pad 0x%"UVxf"[0x%"UVxf"] restore_local\n",       \
354               PTR2UV(PL_comppad), PTR2UV(PL_curpad)));
355
356
357 /*
358 =for apidoc m|void|CX_CURPAD_SAVE|struct context
359 Save the current pad in the given context block structure.
360
361 =for apidoc m|SV *|CX_CURPAD_SV|struct context|PADOFFSET po
362 Access the SV at offset po in the saved current pad in the given
363 context block structure (can be used as an lvalue).
364
365 =cut
366 */
367
368 #define CX_CURPAD_SAVE(block)  (block).oldcomppad = PL_comppad
369 #define CX_CURPAD_SV(block,po) (AvARRAY(MUTABLE_AV(((block).oldcomppad)))[po])
370
371
372 /*
373 =for apidoc m|U32|PAD_COMPNAME_FLAGS|PADOFFSET po
374 Return the flags for the current compiling pad name
375 at offset C<po>. Assumes a valid slot entry.
376
377 =for apidoc m|char *|PAD_COMPNAME_PV|PADOFFSET po
378 Return the name of the current compiling pad name
379 at offset C<po>. Assumes a valid slot entry.
380
381 =for apidoc m|HV *|PAD_COMPNAME_TYPE|PADOFFSET po
382 Return the type (stash) of the current compiling pad name at offset
383 C<po>. Must be a valid name. Returns null if not typed.
384
385 =for apidoc m|HV *|PAD_COMPNAME_OURSTASH|PADOFFSET po
386 Return the stash associated with an C<our> variable.
387 Assumes the slot entry is a valid C<our> lexical.
388
389 =for apidoc m|STRLEN|PAD_COMPNAME_GEN|PADOFFSET po
390 The generation number of the name at offset C<po> in the current
391 compiling pad (lvalue). Note that C<SvUVX> is hijacked for this purpose.
392
393 =for apidoc m|STRLEN|PAD_COMPNAME_GEN_set|PADOFFSET po|int gen
394 Sets the generation number of the name at offset C<po> in the current
395 ling pad (lvalue) to C<gen>.  Note that C<SvUV_set> is hijacked for this purpose.
396
397 =cut
398
399 */
400
401 #define PAD_COMPNAME(po)        PAD_COMPNAME_SV(po)
402 #define PAD_COMPNAME_SV(po) (*av_fetch(PL_comppad_name, (po), FALSE))
403 #define PAD_COMPNAME_FLAGS(po) SvFLAGS(PAD_COMPNAME_SV(po))
404 #define PAD_COMPNAME_FLAGS_isOUR(po) SvPAD_OUR(PAD_COMPNAME_SV(po))
405 #define PAD_COMPNAME_PV(po) SvPV_nolen(PAD_COMPNAME_SV(po))
406
407 #define PAD_COMPNAME_TYPE(po) pad_compname_type(po)
408
409 #define PAD_COMPNAME_OURSTASH(po) \
410     (SvOURSTASH(PAD_COMPNAME_SV(po)))
411
412 #define PAD_COMPNAME_GEN(po) ((STRLEN)SvUVX(AvARRAY(PL_comppad_name)[po]))
413
414 #define PAD_COMPNAME_GEN_set(po, gen) SvUV_set(AvARRAY(PL_comppad_name)[po], (UV)(gen))
415
416
417 /*
418 =for apidoc m|void|PAD_CLONE_VARS|PerlInterpreter *proto_perl|CLONE_PARAMS* param
419 Clone the state variables associated with running and compiling pads.
420
421 =cut
422 */
423
424 /* NB - we set PL_comppad to null unless it points at a value that
425  * has already been dup'ed, ie it points to part of an active padlist.
426  * Otherwise PL_comppad ends up being a leaked scalar in code like
427  * the following:
428  *     threads->create(sub { threads->create(sub {...} ) } );
429  * where the second thread dups the outer sub's comppad but not the
430  * sub's CV or padlist. */
431
432 #define PAD_CLONE_VARS(proto_perl, param)                               \
433     PL_comppad                  = av_dup(proto_perl->Icomppad, param);  \
434     PL_curpad = PL_comppad ?  AvARRAY(PL_comppad) : NULL;               \
435     PL_comppad_name             = av_dup(proto_perl->Icomppad_name, param); \
436     PL_comppad_name_fill        = proto_perl->Icomppad_name_fill;       \
437     PL_comppad_name_floor       = proto_perl->Icomppad_name_floor;      \
438     PL_min_intro_pending        = proto_perl->Imin_intro_pending;       \
439     PL_max_intro_pending        = proto_perl->Imax_intro_pending;       \
440     PL_padix                    = proto_perl->Ipadix;                   \
441     PL_padix_floor              = proto_perl->Ipadix_floor;             \
442     PL_pad_reset_pending        = proto_perl->Ipad_reset_pending;       \
443     PL_cop_seqmax               = proto_perl->Icop_seqmax;
444
445 /*
446 =for apidoc Am|PADOFFSET|pad_add_name_pvs|const char *name|U32 flags|HV *typestash|HV *ourstash
447
448 Exactly like L</pad_add_name_pvn>, but takes a literal string instead
449 of a string/length pair.
450
451 =cut
452 */
453
454 #define pad_add_name_pvs(name,flags,typestash,ourstash) \
455     Perl_pad_add_name_pvn(aTHX_ STR_WITH_LEN(name), flags, typestash, ourstash)
456
457 /*
458 =for apidoc Am|PADOFFSET|pad_findmy_pvs|const char *name|U32 flags
459
460 Exactly like L</pad_findmy_pvn>, but takes a literal string instead
461 of a string/length pair.
462
463 =cut
464 */
465
466 #define pad_findmy_pvs(name,flags) \
467     Perl_pad_findmy_pvn(aTHX_ STR_WITH_LEN(name), flags)
468
469 /*
470  * Local variables:
471  * c-indentation-style: bsd
472  * c-basic-offset: 4
473  * indent-tabs-mode: nil
474  * End:
475  *
476  * ex: set ts=8 sts=4 sw=4 et:
477  */