[perl5.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 DM	1	/* pad.h
dd2155a4 DM	2	*
4bb101f2	3	* Copyright (C) 2002, by Larry Wall and others
dd2155a4 DM	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 DM	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 DM	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 DM	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 DM	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 DM	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 DM	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 DM	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 DM	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 DM	108	=for apidoc m\|void\|PAD_SET_CUR_NOSAVE \|PADLIST padlist\|I32 n
	109	like PAD_SET_CUR, but without the save
	110
dd2155a4 DM	111	=for apidoc m\|void\|PAD_SAVE_SETNULLPAD
	112	Save the current pad then set it to null.
	113
f3548bdc DM	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 DM	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 DM	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 DM	147	#define PAD_SET_CUR(padlist,n) \
	148	SAVECOMPPAD(); \
	149	PAD_SET_CUR_NOSAVE(padlist,n);
	150
	151
f3548bdc DM	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 DM	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 DM	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 DM	183	#define CX_CURPAD_SAVE(block) (block).oldcomppad = PL_comppad
f3548bdc DM	184	#define CX_CURPAD_SV(block,po) (AvARRAY((AV*)((block).oldcomppad))[po])
dd2155a4 DM	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 DM	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 DM	259	PL_comppad = ptr_table_fetch(PL_ptr_table, proto_perl->Icomppad); \
c5ab0850 DM	260	PL_curpad = PL_comppad ? AvARRAY(PL_comppad) : Null(SV**); \
dd2155a4 DM	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 DM	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;