[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_SET_CUR_NOSAVE	|PADLIST padlist|I32 n
like PAD_SET_CUR, but without the save

=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_NOSAVE(padlist,n) \
	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_SET_CUR(padlist,n) \
	SAVECOMPPAD();						\
	PAD_SET_CUR_NOSAVE(padlist,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
4e380990	108	=for apidoc m\|void\|PAD_SET_CUR_NOSAVE \|PADLIST padlist\|I32 n
	109	like PAD_SET_CUR, but without the save
	110
dd2155a4	111	=for apidoc m\|void\|PAD_SAVE_SETNULLPAD
	112	Save the current pad then set it to null.
	113
f3548bdc	114	=for apidoc m\|void\|PAD_SAVE_LOCAL\|PAD opad\|PAD npad
	115	Save the current pad to the local variable opad, then make the
	116	current pad equal to npad
	117
	118	=for apidoc m\|void\|PAD_RESTORE_LOCAL\|PAD *opad
	119	Restore the old pad saved into the local variable opad by PAD_SAVE_LOCAL()
dd2155a4	120
	121	=cut
	122	*/
	123
	124	#ifdef DEBUGGING
	125	# define PAD_SV(po) pad_sv(po)
	126	# define PAD_SETSV(po,sv) pad_setsv(po,sv)
	127	#else
	128	# define PAD_SV(po) (PL_curpad[po])
	129	# define PAD_SETSV(po,sv) PL_curpad[po] = (sv)
	130	#endif
	131
	132	#define PAD_SVl(po) (PL_curpad[po])
	133
	134	#define PAD_BASE_SV(padlist, po) \
	135	(AvARRAY(padlist)[1]) \
	136	? AvARRAY((AV*)(AvARRAY(padlist)[1]))[po] : Nullsv;
	137
	138
4e380990	139	#define PAD_SET_CUR_NOSAVE(padlist,n) \
f3548bdc	140	PL_comppad = (PAD*) (AvARRAY(padlist)[n]); \
	141	PL_curpad = AvARRAY(PL_comppad); \
	142	DEBUG_Xv(PerlIO_printf(Perl_debug_log, \
	143	"Pad 0x%"UVxf"[0x%"UVxf"] set_cur depth=%d\n", \
	144	PTR2UV(PL_comppad), PTR2UV(PL_curpad), (int)(n)));
	145
	146
4e380990	147	#define PAD_SET_CUR(padlist,n) \
	148	SAVECOMPPAD(); \
	149	PAD_SET_CUR_NOSAVE(padlist,n);
	150
	151
f3548bdc	152	#define PAD_SAVE_SETNULLPAD() SAVECOMPPAD(); \
	153	PL_comppad = Null(PAD); PL_curpad = Null(SV*); \
	154	DEBUG_Xv(PerlIO_printf(Perl_debug_log, "Pad set_null\n"));
	155
	156	#define PAD_SAVE_LOCAL(opad,npad) \
	157	opad = PL_comppad; \
	158	PL_comppad = (npad); \
	159	PL_curpad = PL_comppad ? AvARRAY(PL_comppad) : Null(SV**); \
	160	DEBUG_Xv(PerlIO_printf(Perl_debug_log, \
	161	"Pad 0x%"UVxf"[0x%"UVxf"] save_local\n", \
	162	PTR2UV(PL_comppad), PTR2UV(PL_curpad)));
	163
	164	#define PAD_RESTORE_LOCAL(opad) \
	165	PL_comppad = opad; \
	166	PL_curpad = PL_comppad ? AvARRAY(PL_comppad) : Null(SV**); \
	167	DEBUG_Xv(PerlIO_printf(Perl_debug_log, \
	168	"Pad 0x%"UVxf"[0x%"UVxf"] restore_local\n", \
	169	PTR2UV(PL_comppad), PTR2UV(PL_curpad)));
dd2155a4	170
	171
	172	/*
	173	=for apidoc m\|void\|CX_CURPAD_SAVE\|struct context
	174	Save the current pad in the given context block structure.
	175
f3548bdc	176	=for apidoc m\|SV *\|CX_CURPAD_SV\|struct context\|PADOFFSET po
dd2155a4	177	Access the SV at offset po in the saved current pad in the given
	178	context block structure (can be used as an lvalue).
	179
	180	=cut
	181	*/
	182
f3548bdc	183	#define CX_CURPAD_SAVE(block) (block).oldcomppad = PL_comppad
f3548bdc	184	#define CX_CURPAD_SV(block,po) (AvARRAY((AV*)((block).oldcomppad))[po])
dd2155a4	185
	186
	187	/*
	188	=for apidoc m\|U32\|PAD_COMPNAME_FLAGS\|PADOFFSET po
	189	Return the flags for the current compiling pad name
	190	at offset C<po>. Assumes a valid slot entry.
	191
	192	=for apidoc m\|char *\|PAD_COMPNAME_PV\|PADOFFSET po
	193	Return the name of the current compiling pad name
	194	at offset C<po>. Assumes a valid slot entry.
	195
	196	=for apidoc m\|HV *\|PAD_COMPNAME_TYPE\|PADOFFSET po
	197	Return the type (stash) of the current compiling pad name at offset
	198	C<po>. Must be a valid name. Returns null if not typed.
	199
	200	=for apidoc m\|HV *\|PAD_COMPNAME_OURSTASH\|PADOFFSET po
	201	Return the stash associated with an C<our> variable.
	202	Assumes the slot entry is a valid C<our> lexical.
	203
	204	=for apidoc m\|STRLEN\|PAD_COMPNAME_GEN\|PADOFFSET po
	205	The generation number of the name at offset C<po> in the current
	206	compiling pad (lvalue). Note that C<SvCUR> is hijacked for this purpose.
	207
	208	=cut
	209	*/
	210
	211	#define PAD_COMPNAME_FLAGS(po) SvFLAGS(*av_fetch(PL_comppad_name, (po), FALSE))
	212	#define PAD_COMPNAME_PV(po) SvPV_nolen(*av_fetch(PL_comppad_name, (po), FALSE))
	213
	214	/* XXX DAPM yuk - using av_fetch twice. Is there a better way? */
	215	#define PAD_COMPNAME_TYPE(po) \
	216	((SvFLAGS(*av_fetch(PL_comppad_name, (po), FALSE)) & SVpad_TYPED) \
	217	? (SvSTASH(*av_fetch(PL_comppad_name, (po), FALSE))) : Nullhv)
	218
	219	#define PAD_COMPNAME_OURSTASH(po) \
	220	(GvSTASH(*av_fetch(PL_comppad_name, (po), FALSE)))
	221
	222	#define PAD_COMPNAME_GEN(po) SvCUR(AvARRAY(PL_comppad_name)[po])
	223
	224
	225
	226
	227	/*
	228	=for apidoc m\|void\|PAD_DUP\|PADLIST dstpad\|PADLIST srcpad\|CLONE_PARAMS* param
	229	Clone a padlist.
	230
	231	=for apidoc m\|void\|PAD_CLONE_VARS\|PerlInterpreter *proto_perl \
	232	\|CLONE_PARAMS* param
	233	Clone the state variables associated with running and compiling pads.
	234
	235	=cut
	236	*/
	237
	238
	239	#define PAD_DUP(dstpad, srcpad, param) \
	240	if ((srcpad) && !AvREAL(srcpad)) { \
	241	/* XXX padlists are real, but pretend to be not */ \
	242	AvREAL_on(srcpad); \
	243	(dstpad) = av_dup_inc((srcpad), param); \
	244	AvREAL_off(srcpad); \
	245	AvREAL_off(dstpad); \
	246	} \
	247	else \
	248	(dstpad) = av_dup_inc((srcpad), param);
249
c5ab0850	250	/* NB - we set PL_comppad to null unless it points at a value that
	251	* has already been dup'ed, ie it points to part of an active padlist.
	252	* Otherwise PL_comppad ends up being a leaked scalar in code like
	253	* the following:
	254	* threads->create(sub { threads->create(sub {...} ) } );
	255	* where the second thread dups the outer sub's comppad but not the
	256	* sub's CV or padlist. */
f3548bdc	257
dd2155a4	258	#define PAD_CLONE_VARS(proto_perl, param) \
c5ab0850	259	PL_comppad = ptr_table_fetch(PL_ptr_table, proto_perl->Icomppad); \
c5ab0850	260	PL_curpad = PL_comppad ? AvARRAY(PL_comppad) : Null(SV**); \
dd2155a4	261	PL_comppad_name = av_dup(proto_perl->Icomppad_name, param); \
	262	PL_comppad_name_fill = proto_perl->Icomppad_name_fill; \
	263	PL_comppad_name_floor = proto_perl->Icomppad_name_floor; \
dd2155a4	264	PL_min_intro_pending = proto_perl->Imin_intro_pending; \
	265	PL_max_intro_pending = proto_perl->Imax_intro_pending; \
	266	PL_padix = proto_perl->Ipadix; \
	267	PL_padix_floor = proto_perl->Ipadix_floor; \
	268	PL_pad_reset_pending = proto_perl->Ipad_reset_pending; \
	269	PL_cop_seqmax = proto_perl->Icop_seqmax;