[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_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 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
	108	=for apidoc m\|void\|PAD_SAVE_SETNULLPAD
	109	Save the current pad then set it to null.
	110
f3548bdc DM	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 DM	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 DM	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 DM	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 DM	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 DM	176	#define CX_CURPAD_SAVE(block) (block).oldcomppad = PL_comppad
f3548bdc DM	177	#define CX_CURPAD_SV(block,po) (AvARRAY((AV*)((block).oldcomppad))[po])
dd2155a4 DM	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 DM	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 DM	252	PL_comppad = ptr_table_fetch(PL_ptr_table, proto_perl->Icomppad); \
c5ab0850 DM	253	PL_curpad = PL_comppad ? AvARRAY(PL_comppad) : Null(SV**); \
dd2155a4 DM	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 DM	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;