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

diff --git a/embed.fnc b/embed.fnc
index af6004c..cca2880 100644 (file)
--- 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 ebdb618..9cbb11c 100644 (file)
--- 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 0d83614..9ea8c8b 100644 (file)
--- 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 437d661..ac872ec 100644 (file)
--- 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 7fc7e84..cc649f0 100644 (file)
--- 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 aba3376..2d0c3a7 100644 (file)
--- 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 fdfbc98..3e3d979 100644 (file)
--- 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: