Fix mro docs.

Subject: Re: mro callbacks patch
From: "Brandon Black" <blblack@gmail.com>
Message-ID: <84621a60704231658o4c85783ere3c3e90dd614c30b@mail.gmail.com>

p4raw-id: //depot/perl@31086

7 files changed, 195 insertions, 69 deletions

diff --git a/embed.fnc b/embed.fnc
index af6004c3bd..cca28807d9 100644
--- a/embed.fnc
+++ b/embed.fnc
@@ -282,16 +282,6 @@ Ap	|void	|gv_efullname4	|NN SV* sv|NN const GV* gv|NULLOK const char* prefix|boo
 Ap	|GV*	|gv_fetchfile	|NN const char* name
 Ap	|GV*	|gv_fetchfile_flags|NN const char *const name|const STRLEN len\
 				|const U32 flags
-ApM	|struct mro_meta*	|mro_meta_init	|NN HV* stash
-#if defined(USE_ITHREADS)
-ApM	|struct mro_meta*	|mro_meta_dup	|NN struct mro_meta* smeta|NN CLONE_PARAMS* param
-#endif
-ApM	|AV*	|mro_get_linear_isa|NN HV* stash
-ApM	|AV*	|mro_get_linear_isa_c3|NN HV* stash|I32 level
-ApM	|AV*	|mro_get_linear_isa_dfs|NN HV* stash|I32 level
-ApM	|void   |mro_isa_changed_in|NN HV* stash
-ApM	|void	|mro_method_changed_in	|NN HV* stash
-ApM	|void   |boot_core_mro
 Apd	|GV*	|gv_fetchmeth	|NULLOK HV* stash|NN const char* name|STRLEN len|I32 level
 Apd	|GV*	|gv_fetchmeth_autoload	|NULLOK HV* stash|NN const char* name|STRLEN len|I32 level
 Apdmb	|GV*	|gv_fetchmethod	|NULLOK HV* stash|NN const char* name
@@ -1867,6 +1857,17 @@ AMdnoP	|int	|Perl_signbit	|NV f
 XEMop	|void	|emulate_cop_io	|NN const COP *const c|NN SV *const sv
 XEMop	|regexp *|get_re_arg|NULLOK SV *sv|U32 flags|NULLOK MAGIC **mgp
 
+p	|struct mro_meta*	|mro_meta_init	|NN HV* stash
+#if defined(USE_ITHREADS)
+p	|struct mro_meta*	|mro_meta_dup	|NN struct mro_meta* smeta|NN CLONE_PARAMS* param
+#endif
+Apd	|AV*	|mro_get_linear_isa|NN HV* stash
+Apd	|AV*	|mro_get_linear_isa_c3|NN HV* stash|I32 level
+Apd	|AV*	|mro_get_linear_isa_dfs|NN HV* stash|I32 level
+pd	|void   |mro_isa_changed_in|NN HV* stash
+Apd	|void	|mro_method_changed_in	|NN HV* stash
+p	|void   |boot_core_mro
+
 END_EXTERN_C
 /*
  * ex: set ts=8 sts=4 sw=4 noet:
diff --git a/embed.h b/embed.h
index ebdb618235..9cbb11c4ca 100644
--- a/embed.h
+++ b/embed.h
@@ -267,16 +267,6 @@
 #define gv_efullname4		Perl_gv_efullname4
 #define gv_fetchfile		Perl_gv_fetchfile
 #define gv_fetchfile_flags	Perl_gv_fetchfile_flags
-#define mro_meta_init		Perl_mro_meta_init
-#if defined(USE_ITHREADS)
-#define mro_meta_dup		Perl_mro_meta_dup
-#endif
-#define mro_get_linear_isa	Perl_mro_get_linear_isa
-#define mro_get_linear_isa_c3	Perl_mro_get_linear_isa_c3
-#define mro_get_linear_isa_dfs	Perl_mro_get_linear_isa_dfs
-#define mro_isa_changed_in	Perl_mro_isa_changed_in
-#define mro_method_changed_in	Perl_mro_method_changed_in
-#define boot_core_mro		Perl_boot_core_mro
 #define gv_fetchmeth		Perl_gv_fetchmeth
 #define gv_fetchmeth_autoload	Perl_gv_fetchmeth_autoload
 #define gv_fetchmethod_autoload	Perl_gv_fetchmethod_autoload
@@ -1894,6 +1884,24 @@
 #endif
 #if !defined(HAS_SIGNBIT)
 #endif
+#ifdef PERL_CORE
+#define mro_meta_init		Perl_mro_meta_init
+#endif
+#if defined(USE_ITHREADS)
+#ifdef PERL_CORE
+#define mro_meta_dup		Perl_mro_meta_dup
+#endif
+#endif
+#define mro_get_linear_isa	Perl_mro_get_linear_isa
+#define mro_get_linear_isa_c3	Perl_mro_get_linear_isa_c3
+#define mro_get_linear_isa_dfs	Perl_mro_get_linear_isa_dfs
+#ifdef PERL_CORE
+#define mro_isa_changed_in	Perl_mro_isa_changed_in
+#endif
+#define mro_method_changed_in	Perl_mro_method_changed_in
+#ifdef PERL_CORE
+#define boot_core_mro		Perl_boot_core_mro
+#endif
 #define ck_anoncode		Perl_ck_anoncode
 #define ck_bitop		Perl_ck_bitop
 #define ck_chdir		Perl_ck_chdir
@@ -2520,16 +2528,6 @@
 #define gv_efullname4(a,b,c,d)	Perl_gv_efullname4(aTHX_ a,b,c,d)
 #define gv_fetchfile(a)		Perl_gv_fetchfile(aTHX_ a)
 #define gv_fetchfile_flags(a,b,c)	Perl_gv_fetchfile_flags(aTHX_ a,b,c)
-#define mro_meta_init(a)	Perl_mro_meta_init(aTHX_ a)
-#if defined(USE_ITHREADS)
-#define mro_meta_dup(a,b)	Perl_mro_meta_dup(aTHX_ a,b)
-#endif
-#define mro_get_linear_isa(a)	Perl_mro_get_linear_isa(aTHX_ a)
-#define mro_get_linear_isa_c3(a,b)	Perl_mro_get_linear_isa_c3(aTHX_ a,b)
-#define mro_get_linear_isa_dfs(a,b)	Perl_mro_get_linear_isa_dfs(aTHX_ a,b)
-#define mro_isa_changed_in(a)	Perl_mro_isa_changed_in(aTHX_ a)
-#define mro_method_changed_in(a)	Perl_mro_method_changed_in(aTHX_ a)
-#define boot_core_mro()		Perl_boot_core_mro(aTHX)
 #define gv_fetchmeth(a,b,c,d)	Perl_gv_fetchmeth(aTHX_ a,b,c,d)
 #define gv_fetchmeth_autoload(a,b,c,d)	Perl_gv_fetchmeth_autoload(aTHX_ a,b,c,d)
 #define gv_fetchmethod_autoload(a,b,c)	Perl_gv_fetchmethod_autoload(aTHX_ a,b,c)
@@ -4163,6 +4161,24 @@
 #endif
 #if defined(PERL_CORE) || defined(PERL_EXT)
 #endif
+#ifdef PERL_CORE
+#define mro_meta_init(a)	Perl_mro_meta_init(aTHX_ a)
+#endif
+#if defined(USE_ITHREADS)
+#ifdef PERL_CORE
+#define mro_meta_dup(a,b)	Perl_mro_meta_dup(aTHX_ a,b)
+#endif
+#endif
+#define mro_get_linear_isa(a)	Perl_mro_get_linear_isa(aTHX_ a)
+#define mro_get_linear_isa_c3(a,b)	Perl_mro_get_linear_isa_c3(aTHX_ a,b)
+#define mro_get_linear_isa_dfs(a,b)	Perl_mro_get_linear_isa_dfs(aTHX_ a,b)
+#ifdef PERL_CORE
+#define mro_isa_changed_in(a)	Perl_mro_isa_changed_in(aTHX_ a)
+#endif
+#define mro_method_changed_in(a)	Perl_mro_method_changed_in(aTHX_ a)
+#ifdef PERL_CORE
+#define boot_core_mro()		Perl_boot_core_mro(aTHX)
+#endif
 #define ck_anoncode(a)		Perl_ck_anoncode(aTHX_ a)
 #define ck_bitop(a)		Perl_ck_bitop(aTHX_ a)
 #define ck_chdir(a)		Perl_ck_chdir(aTHX_ a)
diff --git a/global.sym b/global.sym
index 0d83614706..9ea8c8b3f8 100644
--- a/global.sym
+++ b/global.sym
@@ -135,14 +135,6 @@ Perl_gv_efullname3
 Perl_gv_efullname4
 Perl_gv_fetchfile
 Perl_gv_fetchfile_flags
-Perl_mro_meta_init
-Perl_mro_meta_dup
-Perl_mro_get_linear_isa
-Perl_mro_get_linear_isa_c3
-Perl_mro_get_linear_isa_dfs
-Perl_mro_isa_changed_in
-Perl_mro_method_changed_in
-Perl_boot_core_mro
 Perl_gv_fetchmeth
 Perl_gv_fetchmeth_autoload
 Perl_gv_fetchmethod
@@ -756,4 +748,8 @@ Perl_my_strlcpy
 Perl_signbit
 Perl_emulate_cop_io
 Perl_get_re_arg
+Perl_mro_get_linear_isa
+Perl_mro_get_linear_isa_c3
+Perl_mro_get_linear_isa_dfs
+Perl_mro_method_changed_in
 # ex: set ro:
diff --git a/mro.c b/mro.c
index 437d66194e..ac872ec1e2 100644
--- a/mro.c
+++ b/mro.c
@@ -554,14 +554,14 @@ Perl_mro_isa_changed_in(pTHX_ HV* stash)
 /*
 =for apidoc mro_method_changed_in
 
-Like C<mro_isa_changed_in>, but invalidates method
-caching on any child classes of the given stash, so
-that they might notice the changes in this one.
+Invalidates method caching on any child classes
+of the given stash, so that they might notice
+the changes in this one.
 
 Ideally, all instances of C<PL_sub_generation++> in
-the perl source should be replaced by calls to this.
-Some already are, but some are more difficult to
-replace.
+the perl source outside of C<mro.c> should be
+replaced by calls to this.  This conversion is
+nearly complete.
 
 Perl has always had problems with method caches
 getting out of sync when one directly manipulates
diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index 7fc7e84236..cc649f0e78 100644
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -2740,6 +2740,99 @@ Found in file util.c
 
 =back
 
+=head1 MRO Functions
+
+=over 8
+
+=item mro_get_linear_isa
+X<mro_get_linear_isa>
+
+Returns either C<mro_get_linear_isa_c3> or
+C<mro_get_linear_isa_dfs> for the given stash,
+dependant upon which MRO is in effect
+for that stash.  The return value is a
+read-only AV*.
+
+You are responsible for C<SvREFCNT_inc()> on the
+return value if you plan to store it anywhere
+semi-permanently (otherwise it might be deleted
+out from under you the next time the cache is
+invalidated).
+
+	AV*	mro_get_linear_isa(HV* stash)
+
+=for hackers
+Found in file mro.c
+
+=item mro_get_linear_isa_c3
+X<mro_get_linear_isa_c3>
+
+Returns the C3 linearization of @ISA
+the given stash.  The return value is a read-only AV*.
+C<level> should be 0 (it is used internally in this
+function's recursion).
+
+You are responsible for C<SvREFCNT_inc()> on the
+return value if you plan to store it anywhere
+semi-permanently (otherwise it might be deleted
+out from under you the next time the cache is
+invalidated).
+
+	AV*	mro_get_linear_isa_c3(HV* stash, I32 level)
+
+=for hackers
+Found in file mro.c
+
+=item mro_get_linear_isa_dfs
+X<mro_get_linear_isa_dfs>
+
+Returns the Depth-First Search linearization of @ISA
+the given stash.  The return value is a read-only AV*.
+C<level> should be 0 (it is used internally in this
+function's recursion).
+
+You are responsible for C<SvREFCNT_inc()> on the
+return value if you plan to store it anywhere
+semi-permanently (otherwise it might be deleted
+out from under you the next time the cache is
+invalidated).
+
+	AV*	mro_get_linear_isa_dfs(HV* stash, I32 level)
+
+=for hackers
+Found in file mro.c
+
+=item mro_method_changed_in
+X<mro_method_changed_in>
+
+Invalidates method caching on any child classes
+of the given stash, so that they might notice
+the changes in this one.
+
+Ideally, all instances of C<PL_sub_generation++> in
+the perl source outside of C<mro.c> should be
+replaced by calls to this.  This conversion is
+nearly complete.
+
+Perl has always had problems with method caches
+getting out of sync when one directly manipulates
+stashes via things like C<%{Foo::} = %{Bar::}> or 
+C<${Foo::}{bar} = ...> or the equivalent.  If
+you do this in core or XS code, call this afterwards
+on the destination stash to get things back in sync.
+
+If you're doing such a thing from pure perl, use
+C<mro::method_changed_in(classname)>, which
+just calls this.
+
+	void	mro_method_changed_in(HV* stash)
+
+=for hackers
+Found in file mro.c
+
+
+=back
+
 =head1 Multicall Functions
 
 =over 8
diff --git a/pod/perlintern.pod b/pod/perlintern.pod
index aba33768a7..2d0c3a7576 100644
--- a/pod/perlintern.pod
+++ b/pod/perlintern.pod
@@ -568,6 +568,25 @@ Found in file mg.c
 
 =back
 
+=head1 MRO Functions
+
+=over 8
+
+=item mro_isa_changed_in
+X<mro_isa_changed_in>
+
+Takes the necessary steps (cache invalidations, mostly)
+when the @ISA of the given package has changed.  Invoked
+by the C<setisa> magic, should not need to invoke directly.
+
+	void	mro_isa_changed_in(HV* stash)
+
+=for hackers
+Found in file mro.c
+
+
+=back
+
 =head1 Pad Data Structures
 
 =over 8
diff --git a/proto.h b/proto.h
index fdfbc986db..3e3d979cc0 100644
--- a/proto.h
+++ b/proto.h
@@ -635,31 +635,6 @@ PERL_CALLCONV GV*	Perl_gv_fetchfile(pTHX_ const char* name)
 PERL_CALLCONV GV*	Perl_gv_fetchfile_flags(pTHX_ const char *const name, const STRLEN len, const U32 flags)
 			__attribute__nonnull__(pTHX_1);
 
-PERL_CALLCONV struct mro_meta*	Perl_mro_meta_init(pTHX_ HV* stash)
-			__attribute__nonnull__(pTHX_1);
-
-#if defined(USE_ITHREADS)
-PERL_CALLCONV struct mro_meta*	Perl_mro_meta_dup(pTHX_ struct mro_meta* smeta, CLONE_PARAMS* param)
-			__attribute__nonnull__(pTHX_1)
-			__attribute__nonnull__(pTHX_2);
-
-#endif
-PERL_CALLCONV AV*	Perl_mro_get_linear_isa(pTHX_ HV* stash)
-			__attribute__nonnull__(pTHX_1);
-
-PERL_CALLCONV AV*	Perl_mro_get_linear_isa_c3(pTHX_ HV* stash, I32 level)
-			__attribute__nonnull__(pTHX_1);
-
-PERL_CALLCONV AV*	Perl_mro_get_linear_isa_dfs(pTHX_ HV* stash, I32 level)
-			__attribute__nonnull__(pTHX_1);
-
-PERL_CALLCONV void	Perl_mro_isa_changed_in(pTHX_ HV* stash)
-			__attribute__nonnull__(pTHX_1);
-
-PERL_CALLCONV void	Perl_mro_method_changed_in(pTHX_ HV* stash)
-			__attribute__nonnull__(pTHX_1);
-
-PERL_CALLCONV void	Perl_boot_core_mro(pTHX);
 PERL_CALLCONV GV*	Perl_gv_fetchmeth(pTHX_ HV* stash, const char* name, STRLEN len, I32 level)
 			__attribute__nonnull__(pTHX_2);
 
@@ -4670,6 +4645,32 @@ PERL_CALLCONV void	Perl_emulate_cop_io(pTHX_ const COP *const c, SV *const sv)
 
 PERL_CALLCONV regexp *	Perl_get_re_arg(pTHX_ SV *sv, U32 flags, MAGIC **mgp);
 
+PERL_CALLCONV struct mro_meta*	Perl_mro_meta_init(pTHX_ HV* stash)
+			__attribute__nonnull__(pTHX_1);
+
+#if defined(USE_ITHREADS)
+PERL_CALLCONV struct mro_meta*	Perl_mro_meta_dup(pTHX_ struct mro_meta* smeta, CLONE_PARAMS* param)
+			__attribute__nonnull__(pTHX_1)
+			__attribute__nonnull__(pTHX_2);
+
+#endif
+PERL_CALLCONV AV*	Perl_mro_get_linear_isa(pTHX_ HV* stash)
+			__attribute__nonnull__(pTHX_1);
+
+PERL_CALLCONV AV*	Perl_mro_get_linear_isa_c3(pTHX_ HV* stash, I32 level)
+			__attribute__nonnull__(pTHX_1);
+
+PERL_CALLCONV AV*	Perl_mro_get_linear_isa_dfs(pTHX_ HV* stash, I32 level)
+			__attribute__nonnull__(pTHX_1);
+
+PERL_CALLCONV void	Perl_mro_isa_changed_in(pTHX_ HV* stash)
+			__attribute__nonnull__(pTHX_1);
+
+PERL_CALLCONV void	Perl_mro_method_changed_in(pTHX_ HV* stash)
+			__attribute__nonnull__(pTHX_1);
+
+PERL_CALLCONV void	Perl_boot_core_mro(pTHX);
+
 END_EXTERN_C
 /*
  * ex: set ts=8 sts=4 sw=4 noet: