[perl5.git] / cv.h

/*    cv.h
 *
 *    Copyright (c) 1991-2002, Larry Wall
 *
 *    You may distribute under the terms of either the GNU General Public
 *    License or the Artistic License, as specified in the README file.
 *
 */

/* This structure much match XPVCV in B/C.pm and the beginning of XPVFM
 * in sv.h  */

struct xpvcv {
    char *	xpv_pv;		/* pointer to malloced string */
    STRLEN	xpv_cur;	/* length of xp_pv as a C string */
    STRLEN	xpv_len;	/* allocated size */
    IV		xof_off;	/* integer value */
    NV		xnv_nv;		/* numeric value, if any */
    MAGIC*	xmg_magic;	/* magic for scalar array */
    HV*		xmg_stash;	/* class package */

    HV *	xcv_stash;
    OP *	xcv_start;
    OP *	xcv_root;
    void	(*xcv_xsub) (pTHX_ CV*);
    ANY		xcv_xsubany;
    GV *	xcv_gv;
    char *	xcv_file;
    long	xcv_depth;	/* >= 2 indicates recursive call */
    AV *	xcv_padlist;
    CV *	xcv_outside;
#ifdef USE_5005THREADS
    perl_mutex *xcv_mutexp;
    struct perl_thread *xcv_owner;	/* current owner thread */
#endif /* USE_5005THREADS */
    cv_flags_t	xcv_flags;
};

/*
=head1 Handy Values

=for apidoc AmU||Nullcv
Null CV pointer.

=head1 CV Manipulation Functions

=for apidoc Am|HV*|CvSTASH|CV* cv
Returns the stash of the CV.

=cut
*/

#define Nullcv Null(CV*)

#define CvSTASH(sv)	((XPVCV*)SvANY(sv))->xcv_stash
#define CvSTART(sv)	((XPVCV*)SvANY(sv))->xcv_start
#define CvROOT(sv)	((XPVCV*)SvANY(sv))->xcv_root
#define CvXSUB(sv)	((XPVCV*)SvANY(sv))->xcv_xsub
#define CvXSUBANY(sv)	((XPVCV*)SvANY(sv))->xcv_xsubany
#define CvGV(sv)	((XPVCV*)SvANY(sv))->xcv_gv
#define CvFILE(sv)	((XPVCV*)SvANY(sv))->xcv_file
#ifdef USE_ITHREADS
#  define CvFILE_set_from_cop(sv, cop)	(CvFILE(sv) = savepv(CopFILE(cop)))
#else
#  define CvFILE_set_from_cop(sv, cop)	(CvFILE(sv) = CopFILE(cop))
#endif
#define CvFILEGV(sv)	(gv_fetchfile(CvFILE(sv)))
#define CvDEPTH(sv)	((XPVCV*)SvANY(sv))->xcv_depth
#define CvPADLIST(sv)	((XPVCV*)SvANY(sv))->xcv_padlist
#define CvOUTSIDE(sv)	((XPVCV*)SvANY(sv))->xcv_outside
#ifdef USE_5005THREADS
#define CvMUTEXP(sv)	((XPVCV*)SvANY(sv))->xcv_mutexp
#define CvOWNER(sv)	((XPVCV*)SvANY(sv))->xcv_owner
#endif /* USE_5005THREADS */
#define CvFLAGS(sv)	((XPVCV*)SvANY(sv))->xcv_flags

#define CVf_CLONE	0x0001	/* anon CV uses external lexicals */
#define CVf_CLONED	0x0002	/* a clone of one of those */
#define CVf_ANON	0x0004	/* CvGV() can't be trusted */
#define CVf_OLDSTYLE	0x0008
#define CVf_UNIQUE	0x0010	/* can't be cloned */
#define CVf_NODEBUG	0x0020	/* no DB::sub indirection for this CV
				   (esp. useful for special XSUBs) */
#define CVf_METHOD	0x0040	/* CV is explicitly marked as a method */
#define CVf_LOCKED	0x0080	/* CV locks itself or first arg on entry */
#define CVf_LVALUE	0x0100  /* CV return value can be used as lvalue */
#define CVf_CONST	0x0200  /* inlinable sub */
/* This symbol for optimised communication between toke.c and op.c: */
#define CVf_BUILTIN_ATTRS	(CVf_METHOD|CVf_LOCKED|CVf_LVALUE)

#define CvCLONE(cv)		(CvFLAGS(cv) & CVf_CLONE)
#define CvCLONE_on(cv)		(CvFLAGS(cv) |= CVf_CLONE)
#define CvCLONE_off(cv)		(CvFLAGS(cv) &= ~CVf_CLONE)

#define CvCLONED(cv)		(CvFLAGS(cv) & CVf_CLONED)
#define CvCLONED_on(cv)		(CvFLAGS(cv) |= CVf_CLONED)
#define CvCLONED_off(cv)	(CvFLAGS(cv) &= ~CVf_CLONED)

#define CvANON(cv)		(CvFLAGS(cv) & CVf_ANON)
#define CvANON_on(cv)		(CvFLAGS(cv) |= CVf_ANON)
#define CvANON_off(cv)		(CvFLAGS(cv) &= ~CVf_ANON)

#ifdef PERL_XSUB_OLDSTYLE
#define CvOLDSTYLE(cv)		(CvFLAGS(cv) & CVf_OLDSTYLE)
#define CvOLDSTYLE_on(cv)	(CvFLAGS(cv) |= CVf_OLDSTYLE)
#define CvOLDSTYLE_off(cv)	(CvFLAGS(cv) &= ~CVf_OLDSTYLE)
#endif

#define CvUNIQUE(cv)		(CvFLAGS(cv) & CVf_UNIQUE)
#define CvUNIQUE_on(cv)		(CvFLAGS(cv) |= CVf_UNIQUE)
#define CvUNIQUE_off(cv)	(CvFLAGS(cv) &= ~CVf_UNIQUE)

#define CvNODEBUG(cv)		(CvFLAGS(cv) & CVf_NODEBUG)
#define CvNODEBUG_on(cv)	(CvFLAGS(cv) |= CVf_NODEBUG)
#define CvNODEBUG_off(cv)	(CvFLAGS(cv) &= ~CVf_NODEBUG)

#define CvMETHOD(cv)		(CvFLAGS(cv) & CVf_METHOD)
#define CvMETHOD_on(cv)		(CvFLAGS(cv) |= CVf_METHOD)
#define CvMETHOD_off(cv)	(CvFLAGS(cv) &= ~CVf_METHOD)

#define CvLOCKED(cv)		(CvFLAGS(cv) & CVf_LOCKED)
#define CvLOCKED_on(cv)		(CvFLAGS(cv) |= CVf_LOCKED)
#define CvLOCKED_off(cv)	(CvFLAGS(cv) &= ~CVf_LOCKED)

#define CvLVALUE(cv)		(CvFLAGS(cv) & CVf_LVALUE)
#define CvLVALUE_on(cv)		(CvFLAGS(cv) |= CVf_LVALUE)
#define CvLVALUE_off(cv)	(CvFLAGS(cv) &= ~CVf_LVALUE)

#define CvEVAL(cv)		(CvUNIQUE(cv) && !SvFAKE(cv))
#define CvEVAL_on(cv)		(CvUNIQUE_on(cv),SvFAKE_off(cv))
#define CvEVAL_off(cv)		CvUNIQUE_off(cv)

/* BEGIN|INIT|END */
#define CvSPECIAL(cv)		(CvUNIQUE(cv) && SvFAKE(cv))
#define CvSPECIAL_on(cv)	(CvUNIQUE_on(cv),SvFAKE_on(cv))
#define CvSPECIAL_off(cv)	(CvUNIQUE_off(cv),SvFAKE_off(cv))

#define CvCONST(cv)		(CvFLAGS(cv) & CVf_CONST)
#define CvCONST_on(cv)		(CvFLAGS(cv) |= CVf_CONST)
#define CvCONST_off(cv)		(CvFLAGS(cv) &= ~CVf_CONST)

/*
=head1 Pad Data Structures

=for apidoc m|AV *|CvPADLIST|CV *cv
CV's can have CvPADLIST(cv) set to point to an AV.

For these purposes "forms" are a kind-of CV, eval""s are too (except they're
not callable at will and are always thrown away after the eval"" is done
executing).

XSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad,
but that is really the callers pad (a slot of which is allocated by
every entersub).

The CvPADLIST AV has does not have AvREAL set, so REFCNT of component items
is managed "manual" (mostly in op.c) rather than normal av.c rules.
The items in the AV are not SVs as for a normal AV, but other AVs:

0'th Entry of the CvPADLIST is an AV which represents the "names" or rather
the "static type information" for lexicals.

The CvDEPTH'th entry of CvPADLIST AV is an AV which is the stack frame at that
depth of recursion into the CV.
The 0'th slot of a frame AV is an AV which is @_.
other entries are storage for variables and op targets.

During compilation:
C<PL_comppad_name> is set the the the names AV.
C<PL_comppad> is set the the frame AV for the frame CvDEPTH == 1.
C<PL_curpad> is set the body of the frame AV (i.e. AvARRAY(PL_comppad)).

Itterating over the names AV itterates over all possible pad
items. Pad slots that are SVs_PADTMP (targets/GVs/constants) end up having
&PL_sv_undef "names" (see pad_alloc()).

Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid names.
The rest are op targets/GVs/constants which are statically allocated
or resolved at compile time.  These don't have names by which they
can be looked up from Perl code at run time through eval"" like
my/our variables can be.  Since they can't be looked up by "name"
but only by their index allocated at compile time (which is usually
in PL_op->op_targ), wasting a name SV for them doesn't make sense.

The SVs in the names AV have their PV being the name of the variable.
NV+1..IV inclusive is a range of cop_seq numbers for which the name is valid.
For typed lexicals name SV is SVt_PVMG and SvSTASH points at the type.

If SvFAKE is set on the name SV then slot in the frame AVs are
a REFCNT'ed references to a lexical from "outside".

If the 'name' is '&' the the corresponding entry in frame AV
is a CV representing a possible closure.
(SvFAKE and name of '&' is not a meaningful combination currently but could
become so if C<my sub foo {}> is implemented.)

=cut
*/
Commit	Line	Data
a0d0e21e	1	/* cv.h
79072805	2	*
eb1102fc	3	* Copyright (c) 1991-2002, Larry Wall
79072805 LW	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	*
79072805 LW	8	*/
79072805 LW	9
57843af0 GS	10	/* This structure much match XPVCV in B/C.pm and the beginning of XPVFM
57843af0 GS	11	* in sv.h */
44a8e56a	12
79072805 LW	13	struct xpvcv {
	14	char * xpv_pv; /* pointer to malloced string */
	15	STRLEN xpv_cur; /* length of xp_pv as a C string */
	16	STRLEN xpv_len; /* allocated size */
a0d0e21e	17	IV xof_off; /* integer value */
65202027	18	NV xnv_nv; /* numeric value, if any */
79072805 LW	19	MAGIC* xmg_magic; /* magic for scalar array */
	20	HV* xmg_stash; /* class package */
	21
	22	HV * xcv_stash;
	23	OP * xcv_start;
	24	OP * xcv_root;
acfe0abc	25	void (xcv_xsub) (pTHX_ CV);
a0d0e21e	26	ANY xcv_xsubany;
8990e307	27	GV * xcv_gv;
57843af0	28	char * xcv_file;
b195d487	29	long xcv_depth; /* >= 2 indicates recursive call */
79072805	30	AV * xcv_padlist;
748a9306	31	CV * xcv_outside;
4d1ff10f	32	#ifdef USE_5005THREADS
12ca11f6	33	perl_mutex *xcv_mutexp;
52e1cb5e	34	struct perl_thread xcv_owner; / current owner thread */
4d1ff10f	35	#endif /* USE_5005THREADS */
77a005ab	36	cv_flags_t xcv_flags;
79072805	37	};
748a9306	38
954c1994	39	/*
ccfc67b7 JH	40	=head1 Handy Values
ccfc67b7 JH	41
954c1994 GS	42	=for apidoc AmU\|\|Nullcv
	43	Null CV pointer.
	44
ccfc67b7 JH	45	=head1 CV Manipulation Functions
ccfc67b7 JH	46
954c1994 GS	47	=for apidoc Am\|HV\|CvSTASH\|CV cv
	48	Returns the stash of the CV.
	49
	50	=cut
	51	*/
	52
79072805	53	#define Nullcv Null(CV*)
a5f75d66	54
79072805 LW	55	#define CvSTASH(sv) ((XPVCV*)SvANY(sv))->xcv_stash
	56	#define CvSTART(sv) ((XPVCV*)SvANY(sv))->xcv_start
	57	#define CvROOT(sv) ((XPVCV*)SvANY(sv))->xcv_root
a0d0e21e LW	58	#define CvXSUB(sv) ((XPVCV*)SvANY(sv))->xcv_xsub
a0d0e21e LW	59	#define CvXSUBANY(sv) ((XPVCV*)SvANY(sv))->xcv_xsubany
8990e307	60	#define CvGV(sv) ((XPVCV*)SvANY(sv))->xcv_gv
57843af0	61	#define CvFILE(sv) ((XPVCV*)SvANY(sv))->xcv_file
a636914a RH	62	#ifdef USE_ITHREADS
	63	# define CvFILE_set_from_cop(sv, cop) (CvFILE(sv) = savepv(CopFILE(cop)))
	64	#else
	65	# define CvFILE_set_from_cop(sv, cop) (CvFILE(sv) = CopFILE(cop))
	66	#endif
9ec2a764	67	#define CvFILEGV(sv) (gv_fetchfile(CvFILE(sv)))
79072805 LW	68	#define CvDEPTH(sv) ((XPVCV*)SvANY(sv))->xcv_depth
79072805 LW	69	#define CvPADLIST(sv) ((XPVCV*)SvANY(sv))->xcv_padlist
748a9306	70	#define CvOUTSIDE(sv) ((XPVCV*)SvANY(sv))->xcv_outside
4d1ff10f	71	#ifdef USE_5005THREADS
11343788	72	#define CvMUTEXP(sv) ((XPVCV*)SvANY(sv))->xcv_mutexp
11343788	73	#define CvOWNER(sv) ((XPVCV*)SvANY(sv))->xcv_owner
4d1ff10f	74	#endif /* USE_5005THREADS */
a5f75d66 AD	75	#define CvFLAGS(sv) ((XPVCV*)SvANY(sv))->xcv_flags
a5f75d66 AD	76
77a005ab MB	77	#define CVf_CLONE 0x0001 /* anon CV uses external lexicals */
	78	#define CVf_CLONED 0x0002 /* a clone of one of those */
	79	#define CVf_ANON 0x0004 /* CvGV() can't be trusted */
	80	#define CVf_OLDSTYLE 0x0008
	81	#define CVf_UNIQUE 0x0010 /* can't be cloned */
	82	#define CVf_NODEBUG 0x0020 /* no DB::sub indirection for this CV
8ebc5c01	83	(esp. useful for special XSUBs) */
77a005ab MB	84	#define CVf_METHOD 0x0040 /* CV is explicitly marked as a method */
77a005ab MB	85	#define CVf_LOCKED 0x0080 /* CV locks itself or first arg on entry */
cd06dffe	86	#define CVf_LVALUE 0x0100 /* CV return value can be used as lvalue */
beab0874	87	#define CVf_CONST 0x0200 /* inlinable sub */
d3cea301 SB	88	/* This symbol for optimised communication between toke.c and op.c: */
d3cea301 SB	89	#define CVf_BUILTIN_ATTRS (CVf_METHOD\|CVf_LOCKED\|CVf_LVALUE)
a5f75d66 AD	90
	91	#define CvCLONE(cv) (CvFLAGS(cv) & CVf_CLONE)
	92	#define CvCLONE_on(cv) (CvFLAGS(cv) \|= CVf_CLONE)
	93	#define CvCLONE_off(cv) (CvFLAGS(cv) &= ~CVf_CLONE)
	94
	95	#define CvCLONED(cv) (CvFLAGS(cv) & CVf_CLONED)
	96	#define CvCLONED_on(cv) (CvFLAGS(cv) \|= CVf_CLONED)
	97	#define CvCLONED_off(cv) (CvFLAGS(cv) &= ~CVf_CLONED)
	98
	99	#define CvANON(cv) (CvFLAGS(cv) & CVf_ANON)
	100	#define CvANON_on(cv) (CvFLAGS(cv) \|= CVf_ANON)
	101	#define CvANON_off(cv) (CvFLAGS(cv) &= ~CVf_ANON)
79072805	102
67caa1fe	103	#ifdef PERL_XSUB_OLDSTYLE
a5f75d66 AD	104	#define CvOLDSTYLE(cv) (CvFLAGS(cv) & CVf_OLDSTYLE)
	105	#define CvOLDSTYLE_on(cv) (CvFLAGS(cv) \|= CVf_OLDSTYLE)
	106	#define CvOLDSTYLE_off(cv) (CvFLAGS(cv) &= ~CVf_OLDSTYLE)
67caa1fe	107	#endif
07055b4c CS	108
	109	#define CvUNIQUE(cv) (CvFLAGS(cv) & CVf_UNIQUE)
	110	#define CvUNIQUE_on(cv) (CvFLAGS(cv) \|= CVf_UNIQUE)
	111	#define CvUNIQUE_off(cv) (CvFLAGS(cv) &= ~CVf_UNIQUE)
8ebc5c01	112
	113	#define CvNODEBUG(cv) (CvFLAGS(cv) & CVf_NODEBUG)
	114	#define CvNODEBUG_on(cv) (CvFLAGS(cv) \|= CVf_NODEBUG)
	115	#define CvNODEBUG_off(cv) (CvFLAGS(cv) &= ~CVf_NODEBUG)
77a005ab MB	116
	117	#define CvMETHOD(cv) (CvFLAGS(cv) & CVf_METHOD)
	118	#define CvMETHOD_on(cv) (CvFLAGS(cv) \|= CVf_METHOD)
	119	#define CvMETHOD_off(cv) (CvFLAGS(cv) &= ~CVf_METHOD)
	120
	121	#define CvLOCKED(cv) (CvFLAGS(cv) & CVf_LOCKED)
	122	#define CvLOCKED_on(cv) (CvFLAGS(cv) \|= CVf_LOCKED)
	123	#define CvLOCKED_off(cv) (CvFLAGS(cv) &= ~CVf_LOCKED)
1aff0e91	124
cd06dffe GS	125	#define CvLVALUE(cv) (CvFLAGS(cv) & CVf_LVALUE)
	126	#define CvLVALUE_on(cv) (CvFLAGS(cv) \|= CVf_LVALUE)
	127	#define CvLVALUE_off(cv) (CvFLAGS(cv) &= ~CVf_LVALUE)
	128
1aff0e91 GS	129	#define CvEVAL(cv) (CvUNIQUE(cv) && !SvFAKE(cv))
	130	#define CvEVAL_on(cv) (CvUNIQUE_on(cv),SvFAKE_off(cv))
	131	#define CvEVAL_off(cv) CvUNIQUE_off(cv)
	132
	133	/* BEGIN\|INIT\|END */
	134	#define CvSPECIAL(cv) (CvUNIQUE(cv) && SvFAKE(cv))
	135	#define CvSPECIAL_on(cv) (CvUNIQUE_on(cv),SvFAKE_on(cv))
	136	#define CvSPECIAL_off(cv) (CvUNIQUE_off(cv),SvFAKE_off(cv))
beab0874 JT	137
	138	#define CvCONST(cv) (CvFLAGS(cv) & CVf_CONST)
	139	#define CvCONST_on(cv) (CvFLAGS(cv) \|= CVf_CONST)
	140	#define CvCONST_off(cv) (CvFLAGS(cv) &= ~CVf_CONST)
a4f1a029 NIS	141
	142	/*
	143	=head1 Pad Data Structures
	144
	145	=for apidoc m\|AV \|CvPADLIST\|CV cv
	146	CV's can have CvPADLIST(cv) set to point to an AV.
	147
	148	For these purposes "forms" are a kind-of CV, eval""s are too (except they're
	149	not callable at will and are always thrown away after the eval"" is done
	150	executing).
	151
	152	XSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad,
	153	but that is really the callers pad (a slot of which is allocated by
	154	every entersub).
	155
	156	The CvPADLIST AV has does not have AvREAL set, so REFCNT of component items
	157	is managed "manual" (mostly in op.c) rather than normal av.c rules.
	158	The items in the AV are not SVs as for a normal AV, but other AVs:
	159
	160	0'th Entry of the CvPADLIST is an AV which represents the "names" or rather
	161	the "static type information" for lexicals.
	162
	163	The CvDEPTH'th entry of CvPADLIST AV is an AV which is the stack frame at that
	164	depth of recursion into the CV.
	165	The 0'th slot of a frame AV is an AV which is @_.
	166	other entries are storage for variables and op targets.
	167
	168	During compilation:
	169	C<PL_comppad_name> is set the the the names AV.
	170	C<PL_comppad> is set the the frame AV for the frame CvDEPTH == 1.
	171	C<PL_curpad> is set the body of the frame AV (i.e. AvARRAY(PL_comppad)).
	172
	173	Itterating over the names AV itterates over all possible pad
	174	items. Pad slots that are SVs_PADTMP (targets/GVs/constants) end up having
	175	&PL_sv_undef "names" (see pad_alloc()).
	176
	177	Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid names.
	178	The rest are op targets/GVs/constants which are statically allocated
	179	or resolved at compile time. These don't have names by which they
	180	can be looked up from Perl code at run time through eval"" like
	181	my/our variables can be. Since they can't be looked up by "name"
	182	but only by their index allocated at compile time (which is usually
	183	in PL_op->op_targ), wasting a name SV for them doesn't make sense.
	184
	185	The SVs in the names AV have their PV being the name of the variable.
	186	NV+1..IV inclusive is a range of cop_seq numbers for which the name is valid.
	187	For typed lexicals name SV is SVt_PVMG and SvSTASH points at the type.
	188
	189	If SvFAKE is set on the name SV then slot in the frame AVs are
	190	a REFCNT'ed references to a lexical from "outside".
	191
	192	If the 'name' is '&' the the corresponding entry in frame AV
	193	is a CV representing a possible closure.
	194	(SvFAKE and name of '&' is not a meaningful combination currently but could
	195	become so if C<my sub foo {}> is implemented.)
	196
	197	=cut
	198	*/
	199