[p5sagit/p5-mst-13.2.git] / pad.h

/*    pad.h
 *
 *    Copyright (C) 2002, by Larry Wall and others
 *
 *    You may distribute under the terms of either the GNU General Public
 *    License or the Artistic License, as specified in the README file.
 *
 * This file defines the types and macros associated with the API for
 * manipulating scratchpads, which are used by perl to store lexical
 * variables, op targets and constants.
 */


/* a padlist is currently just an AV; but that might change,
 * so hide the type. Ditto a pad.  */

typedef AV PADLIST;
typedef AV PAD;


/* offsets within a pad */

#if PTRSIZE == 4
typedef U32TYPE PADOFFSET;
#else
#   if PTRSIZE == 8
typedef U64TYPE PADOFFSET;
#   endif
#endif
#define NOT_IN_PAD ((PADOFFSET) -1)
 

/* flags for the pad_new() function */

#define padnew_CLONE	1	/* this pad is for a cloned CV */
#define padnew_SAVE	2	/* save old globals */
#define padnew_SAVESUB	4	/* also save extra stuff for start of sub */

/* values for the pad_tidy() function */

typedef enum {
	padtidy_SUB,		/* tidy up a pad for a sub, */
	padtidy_SUBCLONE,	/* a cloned sub, */
	padtidy_FORMAT		/* or a format */
} padtidy_type;

/* ASSERT_CURPAD_LEGAL and ASSERT_CURPAD_ACTIVE respectively determine
 * whether PL_comppad and PL_curpad are consistent and whether they have
 * active values */

#ifdef DEBUGGING
#  define ASSERT_CURPAD_LEGAL(label) \
    if (PL_comppad ? (AvARRAY(PL_comppad) != PL_curpad) : (PL_curpad != 0))  \
	Perl_croak(aTHX_ "panic: illegal pad in %s: 0x%"UVxf"[0x%"UVxf"]",\
	    label, PTR2UV(PL_comppad), PTR2UV(PL_curpad));


#  define ASSERT_CURPAD_ACTIVE(label) \
    if (!PL_comppad || (AvARRAY(PL_comppad) != PL_curpad))		  \
	Perl_croak(aTHX_ "panic: invalid pad in %s: 0x%"UVxf"[0x%"UVxf"]",\
	    label, PTR2UV(PL_comppad), PTR2UV(PL_curpad));
#else
#  define ASSERT_CURPAD_LEGAL(label)
#  define ASSERT_CURPAD_ACTIVE(label)
#endif


/* Note: the following three macros are actually defined in scope.h, but
 * they are documented here for completeness, since they directly or
 * indirectly affect pads.

=for apidoc m|void|SAVEPADSV	|PADOFFSET po
Save a pad slot (used to restore after an iteration)

XXX DAPM it would make more sense to make the arg a PADOFFSET
=for apidoc m|void|SAVECLEARSV	|SV **svp
Clear the pointed to pad value on scope exit. (ie the runtime action of 'my')

=for apidoc m|void|SAVECOMPPAD
save PL_comppad and PL_curpad


=for apidoc m|SV *|PAD_SETSV	|PADOFFSET po|SV* sv
Set the slot at offset C<po> in the current pad to C<sv>

=for apidoc m|void|PAD_SV	|PADOFFSET po
Get the value at offset C<po> in the current pad

=for apidoc m|SV *|PAD_SVl	|PADOFFSET po
Lightweight and lvalue version of C<PAD_SV>.
Get or set the value at offset C<po> in the current pad.
Unlike C<PAD_SV>, does not print diagnostics with -DX.
For internal use only.

=for apidoc m|SV *|PAD_BASE_SV	|PADLIST padlist|PADOFFSET po
Get the value from slot C<po> in the base (DEPTH=1) pad of a padlist

=for apidoc m|void|PAD_SET_CUR	|PADLIST padlist|I32 n
Set the current pad to be pad C<n> in the padlist, saving
the previous current pad.

=for apidoc m|void|PAD_SAVE_SETNULLPAD
Save the current pad then set it to null.

=for apidoc m|void|PAD_SAVE_LOCAL|PAD *opad|PAD *npad
Save the current pad to the local variable opad, then make the
current pad equal to npad

=for apidoc m|void|PAD_RESTORE_LOCAL|PAD *opad
Restore the old pad saved into the local variable opad by PAD_SAVE_LOCAL()

=cut
*/

#ifdef DEBUGGING
#  define PAD_SV(po)	   pad_sv(po)
#  define PAD_SETSV(po,sv) pad_setsv(po,sv)
#else
#  define PAD_SV(po)       (PL_curpad[po])
#  define PAD_SETSV(po,sv) PL_curpad[po] = (sv)
#endif

#define PAD_SVl(po)       (PL_curpad[po])

#define PAD_BASE_SV(padlist, po) \
	(AvARRAY(padlist)[1]) 	\
	    ? AvARRAY((AV*)(AvARRAY(padlist)[1]))[po] : Nullsv;
    

#define PAD_SET_CUR(padlist,n) \
	SAVECOMPPAD();						\
	PL_comppad = (PAD*) (AvARRAY(padlist)[n]);		\
	PL_curpad = AvARRAY(PL_comppad);			\
	DEBUG_Xv(PerlIO_printf(Perl_debug_log,			\
	      "Pad 0x%"UVxf"[0x%"UVxf"] set_cur    depth=%d\n",	\
	      PTR2UV(PL_comppad), PTR2UV(PL_curpad), (int)(n)));


#define PAD_SAVE_SETNULLPAD()	SAVECOMPPAD(); \
	PL_comppad = Null(PAD*); PL_curpad = Null(SV**);	\
	DEBUG_Xv(PerlIO_printf(Perl_debug_log, "Pad set_null\n"));

#define PAD_SAVE_LOCAL(opad,npad) \
	opad = PL_comppad;					\
	PL_comppad = (npad);					\
	PL_curpad =  PL_comppad ? AvARRAY(PL_comppad) : Null(SV**); \
	DEBUG_Xv(PerlIO_printf(Perl_debug_log,			\
	      "Pad 0x%"UVxf"[0x%"UVxf"] save_local\n",		\
	      PTR2UV(PL_comppad), PTR2UV(PL_curpad)));

#define PAD_RESTORE_LOCAL(opad) \
	PL_comppad = opad;					\
	PL_curpad =  PL_comppad ? AvARRAY(PL_comppad) : Null(SV**); \
	DEBUG_Xv(PerlIO_printf(Perl_debug_log,			\
	      "Pad 0x%"UVxf"[0x%"UVxf"] restore_local\n",	\
	      PTR2UV(PL_comppad), PTR2UV(PL_curpad)));


/*
=for apidoc m|void|CX_CURPAD_SAVE|struct context
Save the current pad in the given context block structure.

=for apidoc m|SV *|CX_CURPAD_SV|struct context|PADOFFSET po
Access the SV at offset po in the saved current pad in the given
context block structure (can be used as an lvalue).

=cut
*/

#define CX_CURPAD_SAVE(block)  (block).oldcomppad = PL_comppad
#define CX_CURPAD_SV(block,po) (AvARRAY((AV*)((block).oldcomppad))[po])


/*
=for apidoc m|U32|PAD_COMPNAME_FLAGS|PADOFFSET po
Return the flags for the current compiling pad name
at offset C<po>. Assumes a valid slot entry.

=for apidoc m|char *|PAD_COMPNAME_PV|PADOFFSET po
Return the name of the current compiling pad name
at offset C<po>. Assumes a valid slot entry.

=for apidoc m|HV *|PAD_COMPNAME_TYPE|PADOFFSET po
Return the type (stash) of the current compiling pad name at offset
C<po>. Must be a valid name. Returns null if not typed.

=for apidoc m|HV *|PAD_COMPNAME_OURSTASH|PADOFFSET po
Return the stash associated with an C<our> variable.
Assumes the slot entry is a valid C<our> lexical.

=for apidoc m|STRLEN|PAD_COMPNAME_GEN|PADOFFSET po
The generation number of the name at offset C<po> in the current
compiling pad (lvalue). Note that C<SvCUR> is hijacked for this purpose.

=cut
*/

#define PAD_COMPNAME_FLAGS(po) SvFLAGS(*av_fetch(PL_comppad_name, (po), FALSE))
#define PAD_COMPNAME_PV(po) SvPV_nolen(*av_fetch(PL_comppad_name, (po), FALSE))

/* XXX DAPM yuk - using av_fetch twice. Is there a better way? */
#define PAD_COMPNAME_TYPE(po) \
    ((SvFLAGS(*av_fetch(PL_comppad_name, (po), FALSE)) & SVpad_TYPED) \
    ? (SvSTASH(*av_fetch(PL_comppad_name, (po), FALSE))) :  Nullhv)

#define PAD_COMPNAME_OURSTASH(po) \
    (GvSTASH(*av_fetch(PL_comppad_name, (po), FALSE)))

#define PAD_COMPNAME_GEN(po) SvCUR(AvARRAY(PL_comppad_name)[po])


/*
=for apidoc m|void|PAD_DUP|PADLIST dstpad|PADLIST srcpad|CLONE_PARAMS* param
Clone a padlist.

=for apidoc m|void|PAD_CLONE_VARS|PerlInterpreter *proto_perl \
|CLONE_PARAMS* param
Clone the state variables associated with running and compiling pads.

=cut
*/


#define PAD_DUP(dstpad, srcpad, param)				\
    if ((srcpad) && !AvREAL(srcpad)) {				\
	/* XXX padlists are real, but pretend to be not */ 	\
	AvREAL_on(srcpad);					\
	(dstpad) = av_dup_inc((srcpad), param);			\
	AvREAL_off(srcpad);					\
	AvREAL_off(dstpad);					\
    }								\
    else							\
	(dstpad) = av_dup_inc((srcpad), param);			

/* NB - we set PL_comppad to null unless it points at a value that
 * has already been dup'ed, ie it points to part of an active padlist.
 * Otherwise PL_comppad ends up being a leaked scalar in code like
 * the following:
 *     threads->create(sub { threads->create(sub {...} ) } );
 * where the second thread dups the outer sub's comppad but not the
 * sub's CV or padlist. */

#define PAD_CLONE_VARS(proto_perl, param)				\
    PL_comppad = ptr_table_fetch(PL_ptr_table, proto_perl->Icomppad);	\
    PL_curpad = PL_comppad ?  AvARRAY(PL_comppad) : Null(SV**);		\
    PL_comppad_name		= av_dup(proto_perl->Icomppad_name, param); \
    PL_comppad_name_fill	= proto_perl->Icomppad_name_fill;	\
    PL_comppad_name_floor	= proto_perl->Icomppad_name_floor;	\
    PL_min_intro_pending	= proto_perl->Imin_intro_pending;	\
    PL_max_intro_pending	= proto_perl->Imax_intro_pending;	\
    PL_padix			= proto_perl->Ipadix;			\
    PL_padix_floor		= proto_perl->Ipadix_floor;		\
    PL_pad_reset_pending	= proto_perl->Ipad_reset_pending;	\
    PL_cop_seqmax		= proto_perl->Icop_seqmax;
Commit	Line	Data
dd2155a4	1	/* pad.h
dd2155a4	2	*
4bb101f2	3	* Copyright (C) 2002, by Larry Wall and others
dd2155a4	4	*
	5	* You may distribute under the terms of either the GNU General Public
	6	* License or the Artistic License, as specified in the README file.
	7	*
	8	* This file defines the types and macros associated with the API for
	9	* manipulating scratchpads, which are used by perl to store lexical
	10	* variables, op targets and constants.
	11	*/
	12
	13
	14
	15
	16	/* a padlist is currently just an AV; but that might change,
	17	* so hide the type. Ditto a pad. */
	18
	19	typedef AV PADLIST;
f3548bdc	20	typedef AV PAD;
dd2155a4	21
	22
	23	/* offsets within a pad */
	24
	25	#if PTRSIZE == 4
	26	typedef U32TYPE PADOFFSET;
	27	#else
	28	# if PTRSIZE == 8
	29	typedef U64TYPE PADOFFSET;
	30	# endif
	31	#endif
	32	#define NOT_IN_PAD ((PADOFFSET) -1)
	33
	34
	35	/* flags for the pad_new() function */
	36
c7c737cb	37	#define padnew_CLONE 1 /* this pad is for a cloned CV */
	38	#define padnew_SAVE 2 /* save old globals */
	39	#define padnew_SAVESUB 4 /* also save extra stuff for start of sub */
dd2155a4	40
	41	/* values for the pad_tidy() function */
	42
	43	typedef enum {
	44	padtidy_SUB, /* tidy up a pad for a sub, */
	45	padtidy_SUBCLONE, /* a cloned sub, */
	46	padtidy_FORMAT /* or a format */
	47	} padtidy_type;
	48
f3548bdc	49	/* ASSERT_CURPAD_LEGAL and ASSERT_CURPAD_ACTIVE respectively determine
	50	* whether PL_comppad and PL_curpad are consistent and whether they have
	51	* active values */
dd2155a4	52
f3548bdc	53	#ifdef DEBUGGING
	54	# define ASSERT_CURPAD_LEGAL(label) \
	55	if (PL_comppad ? (AvARRAY(PL_comppad) != PL_curpad) : (PL_curpad != 0)) \
	56	Perl_croak(aTHX_ "panic: illegal pad in %s: 0x%"UVxf"[0x%"UVxf"]",\
	57	label, PTR2UV(PL_comppad), PTR2UV(PL_curpad));
	58
	59
	60	# define ASSERT_CURPAD_ACTIVE(label) \
	61	if (!PL_comppad \|\| (AvARRAY(PL_comppad) != PL_curpad)) \
	62	Perl_croak(aTHX_ "panic: invalid pad in %s: 0x%"UVxf"[0x%"UVxf"]",\
	63	label, PTR2UV(PL_comppad), PTR2UV(PL_curpad));
	64	#else
	65	# define ASSERT_CURPAD_LEGAL(label)
	66	# define ASSERT_CURPAD_ACTIVE(label)
	67	#endif
	68
	69
	70
	71	/* Note: the following three macros are actually defined in scope.h, but
dd2155a4	72	* they are documented here for completeness, since they directly or
	73	* indirectly affect pads.
	74
	75	=for apidoc m\|void\|SAVEPADSV \|PADOFFSET po
	76	Save a pad slot (used to restore after an iteration)
	77
f3548bdc	78	XXX DAPM it would make more sense to make the arg a PADOFFSET
dd2155a4	79	=for apidoc m\|void\|SAVECLEARSV \|SV **svp
	80	Clear the pointed to pad value on scope exit. (ie the runtime action of 'my')
	81
	82	=for apidoc m\|void\|SAVECOMPPAD
	83	save PL_comppad and PL_curpad
	84
dd2155a4	85
	86
	87
	88
	89	=for apidoc m\|SV \|PAD_SETSV \|PADOFFSET po\|SV sv
	90	Set the slot at offset C<po> in the current pad to C<sv>
	91
	92	=for apidoc m\|void\|PAD_SV \|PADOFFSET po
	93	Get the value at offset C<po> in the current pad
	94
	95	=for apidoc m\|SV *\|PAD_SVl \|PADOFFSET po
	96	Lightweight and lvalue version of C<PAD_SV>.
	97	Get or set the value at offset C<po> in the current pad.
	98	Unlike C<PAD_SV>, does not print diagnostics with -DX.
	99	For internal use only.
	100
	101	=for apidoc m\|SV *\|PAD_BASE_SV \|PADLIST padlist\|PADOFFSET po
	102	Get the value from slot C<po> in the base (DEPTH=1) pad of a padlist
	103
	104	=for apidoc m\|void\|PAD_SET_CUR \|PADLIST padlist\|I32 n
	105	Set the current pad to be pad C<n> in the padlist, saving
	106	the previous current pad.
	107
	108	=for apidoc m\|void\|PAD_SAVE_SETNULLPAD
	109	Save the current pad then set it to null.
	110
f3548bdc	111	=for apidoc m\|void\|PAD_SAVE_LOCAL\|PAD opad\|PAD npad
	112	Save the current pad to the local variable opad, then make the
	113	current pad equal to npad
	114
	115	=for apidoc m\|void\|PAD_RESTORE_LOCAL\|PAD *opad
	116	Restore the old pad saved into the local variable opad by PAD_SAVE_LOCAL()
dd2155a4	117
	118	=cut
	119	*/
	120
	121	#ifdef DEBUGGING
	122	# define PAD_SV(po) pad_sv(po)
	123	# define PAD_SETSV(po,sv) pad_setsv(po,sv)
	124	#else
	125	# define PAD_SV(po) (PL_curpad[po])
	126	# define PAD_SETSV(po,sv) PL_curpad[po] = (sv)
	127	#endif
	128
	129	#define PAD_SVl(po) (PL_curpad[po])
	130
	131	#define PAD_BASE_SV(padlist, po) \
	132	(AvARRAY(padlist)[1]) \
	133	? AvARRAY((AV*)(AvARRAY(padlist)[1]))[po] : Nullsv;
	134
	135
	136	#define PAD_SET_CUR(padlist,n) \
f3548bdc	137	SAVECOMPPAD(); \
	138	PL_comppad = (PAD*) (AvARRAY(padlist)[n]); \
	139	PL_curpad = AvARRAY(PL_comppad); \
	140	DEBUG_Xv(PerlIO_printf(Perl_debug_log, \
	141	"Pad 0x%"UVxf"[0x%"UVxf"] set_cur depth=%d\n", \
	142	PTR2UV(PL_comppad), PTR2UV(PL_curpad), (int)(n)));
	143
	144
	145	#define PAD_SAVE_SETNULLPAD() SAVECOMPPAD(); \
	146	PL_comppad = Null(PAD); PL_curpad = Null(SV*); \
	147	DEBUG_Xv(PerlIO_printf(Perl_debug_log, "Pad set_null\n"));
	148
	149	#define PAD_SAVE_LOCAL(opad,npad) \
	150	opad = PL_comppad; \
	151	PL_comppad = (npad); \
	152	PL_curpad = PL_comppad ? AvARRAY(PL_comppad) : Null(SV**); \
	153	DEBUG_Xv(PerlIO_printf(Perl_debug_log, \
	154	"Pad 0x%"UVxf"[0x%"UVxf"] save_local\n", \
	155	PTR2UV(PL_comppad), PTR2UV(PL_curpad)));
	156
	157	#define PAD_RESTORE_LOCAL(opad) \
	158	PL_comppad = opad; \
	159	PL_curpad = PL_comppad ? AvARRAY(PL_comppad) : Null(SV**); \
	160	DEBUG_Xv(PerlIO_printf(Perl_debug_log, \
	161	"Pad 0x%"UVxf"[0x%"UVxf"] restore_local\n", \
	162	PTR2UV(PL_comppad), PTR2UV(PL_curpad)));
dd2155a4	163
	164
	165	/*
	166	=for apidoc m\|void\|CX_CURPAD_SAVE\|struct context
	167	Save the current pad in the given context block structure.
	168
f3548bdc	169	=for apidoc m\|SV *\|CX_CURPAD_SV\|struct context\|PADOFFSET po
dd2155a4	170	Access the SV at offset po in the saved current pad in the given
	171	context block structure (can be used as an lvalue).
	172
	173	=cut
	174	*/
	175
f3548bdc	176	#define CX_CURPAD_SAVE(block) (block).oldcomppad = PL_comppad
f3548bdc	177	#define CX_CURPAD_SV(block,po) (AvARRAY((AV*)((block).oldcomppad))[po])
dd2155a4	178
	179
	180	/*
	181	=for apidoc m\|U32\|PAD_COMPNAME_FLAGS\|PADOFFSET po
	182	Return the flags for the current compiling pad name
	183	at offset C<po>. Assumes a valid slot entry.
	184
	185	=for apidoc m\|char *\|PAD_COMPNAME_PV\|PADOFFSET po
	186	Return the name of the current compiling pad name
	187	at offset C<po>. Assumes a valid slot entry.
	188
	189	=for apidoc m\|HV *\|PAD_COMPNAME_TYPE\|PADOFFSET po
	190	Return the type (stash) of the current compiling pad name at offset
	191	C<po>. Must be a valid name. Returns null if not typed.
	192
	193	=for apidoc m\|HV *\|PAD_COMPNAME_OURSTASH\|PADOFFSET po
	194	Return the stash associated with an C<our> variable.
	195	Assumes the slot entry is a valid C<our> lexical.
	196
	197	=for apidoc m\|STRLEN\|PAD_COMPNAME_GEN\|PADOFFSET po
	198	The generation number of the name at offset C<po> in the current
	199	compiling pad (lvalue). Note that C<SvCUR> is hijacked for this purpose.
	200
	201	=cut
	202	*/
	203
	204	#define PAD_COMPNAME_FLAGS(po) SvFLAGS(*av_fetch(PL_comppad_name, (po), FALSE))
	205	#define PAD_COMPNAME_PV(po) SvPV_nolen(*av_fetch(PL_comppad_name, (po), FALSE))
	206
	207	/* XXX DAPM yuk - using av_fetch twice. Is there a better way? */
	208	#define PAD_COMPNAME_TYPE(po) \
	209	((SvFLAGS(*av_fetch(PL_comppad_name, (po), FALSE)) & SVpad_TYPED) \
	210	? (SvSTASH(*av_fetch(PL_comppad_name, (po), FALSE))) : Nullhv)
	211
	212	#define PAD_COMPNAME_OURSTASH(po) \
	213	(GvSTASH(*av_fetch(PL_comppad_name, (po), FALSE)))
	214
	215	#define PAD_COMPNAME_GEN(po) SvCUR(AvARRAY(PL_comppad_name)[po])
	216
	217
	218
	219
	220	/*
	221	=for apidoc m\|void\|PAD_DUP\|PADLIST dstpad\|PADLIST srcpad\|CLONE_PARAMS* param
	222	Clone a padlist.
	223
	224	=for apidoc m\|void\|PAD_CLONE_VARS\|PerlInterpreter *proto_perl \
	225	\|CLONE_PARAMS* param
	226	Clone the state variables associated with running and compiling pads.
	227
	228	=cut
	229	*/
	230
	231
	232	#define PAD_DUP(dstpad, srcpad, param) \
	233	if ((srcpad) && !AvREAL(srcpad)) { \
	234	/* XXX padlists are real, but pretend to be not */ \
	235	AvREAL_on(srcpad); \
	236	(dstpad) = av_dup_inc((srcpad), param); \
	237	AvREAL_off(srcpad); \
	238	AvREAL_off(dstpad); \
	239	} \
	240	else \
	241	(dstpad) = av_dup_inc((srcpad), param);
242
c5ab0850	243	/* NB - we set PL_comppad to null unless it points at a value that
	244	* has already been dup'ed, ie it points to part of an active padlist.
	245	* Otherwise PL_comppad ends up being a leaked scalar in code like
	246	* the following:
	247	* threads->create(sub { threads->create(sub {...} ) } );
	248	* where the second thread dups the outer sub's comppad but not the
	249	* sub's CV or padlist. */
f3548bdc	250
dd2155a4	251	#define PAD_CLONE_VARS(proto_perl, param) \
c5ab0850	252	PL_comppad = ptr_table_fetch(PL_ptr_table, proto_perl->Icomppad); \
c5ab0850	253	PL_curpad = PL_comppad ? AvARRAY(PL_comppad) : Null(SV**); \
dd2155a4	254	PL_comppad_name = av_dup(proto_perl->Icomppad_name, param); \
	255	PL_comppad_name_fill = proto_perl->Icomppad_name_fill; \
	256	PL_comppad_name_floor = proto_perl->Icomppad_name_floor; \
dd2155a4	257	PL_min_intro_pending = proto_perl->Imin_intro_pending; \
	258	PL_max_intro_pending = proto_perl->Imax_intro_pending; \
	259	PL_padix = proto_perl->Ipadix; \
	260	PL_padix_floor = proto_perl->Ipadix_floor; \
	261	PL_pad_reset_pending = proto_perl->Ipad_reset_pending; \
	262	PL_cop_seqmax = proto_perl->Icop_seqmax;