From: Brandon Black Date: Mon, 23 Apr 2007 18:58:39 +0000 (-0500) Subject: Fix mro docs. X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=47c9dd1447a52d200f008e3cc2f93e7266eb217e;p=p5sagit%2Fp5-mst-13.2.git Fix mro docs. Subject: Re: mro callbacks patch From: "Brandon Black" Message-ID: <84621a60704231658o4c85783ere3c3e90dd614c30b@mail.gmail.com> p4raw-id: //depot/perl@31086 --- diff --git a/embed.fnc b/embed.fnc index af6004c..cca2880 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 ebdb618..9cbb11c4 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 0d83614..9ea8c8b 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 437d661..ac872ec 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, 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 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 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 --- 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 + +Returns either C or +C 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 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 + +Returns the C3 linearization of @ISA +the given stash. The return value is a read-only AV*. +C should be 0 (it is used internally in this +function's recursion). + +You are responsible for C 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 + +Returns the Depth-First Search linearization of @ISA +the given stash. The return value is a read-only AV*. +C should be 0 (it is used internally in this +function's recursion). + +You are responsible for C 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 + +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 in +the perl source outside of 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, 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 --- 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 + +Takes the necessary steps (cache invalidations, mostly) +when the @ISA of the given package has changed. Invoked +by the C 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 --- 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: