Add documentation for the method resolution plugin interface.

diff --git a/MANIFEST b/MANIFEST
index bbc5ee2..017b28b 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -3635,6 +3635,7 @@ pod/perlmodinstall.pod            Perl modules: how to install from CPAN
 pod/perlmodlib.PL              Generate pod/perlmodlib.pod
 pod/perlmod.pod                        Perl modules: how they work
 pod/perlmodstyle.pod           Perl modules: how to write modules with style
+pod/perlmroapi.pod             Perl method resolution plugin interface
 pod/perlnewmod.pod             Perl modules: preparing a new module for distribution
 pod/perlnumber.pod             Perl number semantics
 pod/perlobj.pod                        Perl objects

diff --git a/pod.lst b/pod.lst
index 0a4a1e8..b68c733 100644 (file)
--- a/pod.lst
+++ b/pod.lst
@@ -112,6 +112,7 @@ h Internals and C Language Interface
   perlclib             Internal replacements for standard C library functions
   perlguts             Perl internal functions for those doing extensions
   perlcall             Perl calling conventions from C
+  perlmroapi           Perl method resolution plugin interface
   perlreapi            Perl regular expression plugin interface
   perlreguts           Perl regular expression engine internals
 

diff --git a/pod/perl.pod b/pod/perl.pod
index d9c20d3..eaf9c59 100644 (file)
--- a/pod/perl.pod
+++ b/pod/perl.pod
@@ -126,6 +126,7 @@ For ease of access, the Perl manual has been split up into several sections.
     perlclib           Internal replacements for standard C library functions
     perlguts           Perl internal functions for those doing extensions
     perlcall           Perl calling conventions from C
+    perlmroapi         Perl method resolution plugin interface
     perlreapi          Perl regular expression plugin interface
     perlreguts         Perl regular expression engine internals
 

diff --git a/pod/perlmroapi.pod b/pod/perlmroapi.pod
new file mode 100644 (file)
index 0000000..2200bec
--- /dev/null
+++ b/pod/perlmroapi.pod
@@ -0,0 +1,94 @@
+=head1 NAME
+
+perlmroapi - Perl method resolution plugin interface
+
+=head1 DESCRIPTION
+
+As of Perl 5.10.1 there is a new interface for plugging and using method
+resolution orders other than the default (linear depth first search).
+The C3 method resolution order added in 5.10.0 has been re-implemented as
+a plugin, without changing its Perl-space interface.
+
+Each plugin should register itself with C<Perl_mro_register> by providing
+the following structure
+
+    struct mro_alg {
+        AV *(*resolve)(pTHX_ HV *stash, U32 level);
+        const char *name;
+        U16 length;
+        U16 kflags;
+        U32 hash;
+    };
+
+=over 4
+
+=item resolve
+
+Pointer to the linearisation function, described below.
+
+=item name
+
+Name of the MRO, either in ISO-8859-1 or UTF-8.
+
+=item length
+
+Length of the name.
+
+=item kflags
+
+If the name is given in UTF-8, set this to C<HVhek_UTF8>. The value is passed
+direct as the parameter I<kflags> to C<hv_common()>.
+
+=item hash
+
+A precomputed hash value for the MRO's name, or 0.
+
+=back
+
+=head1 Callbacks
+
+The C<resolve> function is called to generate a linearised ISA for the
+given stash, using this MRO. It is called with a pointer to the stash, and
+a I<level> of 0. The core always sets I<level> to 0 when it calls your
+function - the parameter is provided to allow your implementation to track
+depth if it needs to recurse.
+
+The function should return a reference to an array containing the parent
+classes in order. The caller is responsible for incrementing the reference
+count if it wants to keep the structure. Hence if you have created a
+temporary value that you keep no pointer to, C<sv_2mortal()> to ensure that
+it is disposed of correctly. If you have cached your return value, then
+return a pointer to it without changing the reference count.
+
+=head1 Caching
+
+Computing MROs can be expensive. The implementation provides a cache, in
+which you can store a single C<SV *>, or anything that can be cast to
+C<SV *>, such as C<AV *>. To read your private value, use the macro
+C<MRO_GET_PRIVATE_DATA()>, passing it the C<mro_meta> structure from the
+stash, and a pointer to your C<mro_alg> structure:
+
+    meta = HvMROMETA(stash);
+    private_sv = MRO_GET_PRIVATE_DATA(meta, &my_mro_alg);
+
+To set your private value, call C<Perl_mro_set_private_data()>:
+
+    Perl_mro_set_private_data(aTHX_ meta, &c3_alg, private_sv);
+
+The private data cache will take ownership of a reference to private_sv,
+much the same way that C<hv_store()> takes ownership of a reference to the
+value that you pass it.
+
+=head1 Examples
+
+For examples of MRO implementations, see C<S_mro_get_linear_isa_c3()>
+and the C<BOOT:> section of F<mro/mro.xs>, and C<S_mro_get_linear_isa_dfs()>
+in F<mro.c>
+
+=head1 AUTHORS
+
+The implementation of the C3 MRO and switchable MROs within the perl core was
+written by Brandon L Black. Nicholas Clark created the pluggable interface, 
+refactored Brandon's implementation to work with it, and wrote this document.
+
+=cut

diff --git a/vms/descrip_mms.template b/vms/descrip_mms.template
index d7d0615..edaacc0 100644 (file)
--- a/vms/descrip_mms.template
+++ b/vms/descrip_mms.template
@@ -418,18 +418,18 @@ pod14 = [.lib.pods]perlglossary.pod [.lib.pods]perlgpl.pod [.lib.pods]perlguts.p
 pod15 = [.lib.pods]perlhpux.pod [.lib.pods]perlhurd.pod [.lib.pods]perlintern.pod [.lib.pods]perlintro.pod [.lib.pods]perliol.pod [.lib.pods]perlipc.pod
 pod16 = [.lib.pods]perlirix.pod [.lib.pods]perljp.pod [.lib.pods]perlko.pod [.lib.pods]perllexwarn.pod [.lib.pods]perllinux.pod [.lib.pods]perllocale.pod
 pod17 = [.lib.pods]perllol.pod [.lib.pods]perlmachten.pod [.lib.pods]perlmacos.pod [.lib.pods]perlmacosx.pod [.lib.pods]perlmint.pod [.lib.pods]perlmod.pod
-pod18 = [.lib.pods]perlmodinstall.pod [.lib.pods]perlmodlib.pod [.lib.pods]perlmodstyle.pod [.lib.pods]perlmpeix.pod [.lib.pods]perlnetware.pod
-pod19 = [.lib.pods]perlnewmod.pod [.lib.pods]perlnumber.pod [.lib.pods]perlobj.pod [.lib.pods]perlop.pod [.lib.pods]perlopenbsd.pod
-pod20 = [.lib.pods]perlopentut.pod [.lib.pods]perlos2.pod [.lib.pods]perlos390.pod [.lib.pods]perlos400.pod [.lib.pods]perlpacktut.pod
-pod21 = [.lib.pods]perlperf.pod [.lib.pods]perlplan9.pod [.lib.pods]perlpod.pod [.lib.pods]perlpodspec.pod [.lib.pods]perlport.pod [.lib.pods]perlpragma.pod
-pod22 = [.lib.pods]perlqnx.pod [.lib.pods]perlre.pod [.lib.pods]perlreapi.pod [.lib.pods]perlrebackslash.pod [.lib.pods]perlrecharclass.pod
-pod23 = [.lib.pods]perlref.pod [.lib.pods]perlreftut.pod [.lib.pods]perlreguts.pod [.lib.pods]perlrepository.pod [.lib.pods]perlrequick.pod
-pod24 = [.lib.pods]perlreref.pod [.lib.pods]perlretut.pod [.lib.pods]perlriscos.pod [.lib.pods]perlrun.pod [.lib.pods]perlsec.pod [.lib.pods]perlsolaris.pod
-pod25 = [.lib.pods]perlstyle.pod [.lib.pods]perlsub.pod [.lib.pods]perlsymbian.pod [.lib.pods]perlsyn.pod [.lib.pods]perlthrtut.pod [.lib.pods]perltie.pod
-pod26 = [.lib.pods]perltoc.pod [.lib.pods]perltodo.pod [.lib.pods]perltooc.pod [.lib.pods]perltoot.pod [.lib.pods]perltrap.pod [.lib.pods]perltru64.pod
-pod27 = [.lib.pods]perltw.pod [.lib.pods]perlunicode.pod [.lib.pods]perlunifaq.pod [.lib.pods]perluniintro.pod [.lib.pods]perlunitut.pod
-pod28 = [.lib.pods]perlutil.pod [.lib.pods]perluts.pod [.lib.pods]perlvar.pod [.lib.pods]perlvmesa.pod [.lib.pods]perlvms.pod [.lib.pods]perlvos.pod
-pod29 = [.lib.pods]perlwin32.pod [.lib.pods]perlxs.pod [.lib.pods]perlxstut.pod
+pod18 = [.lib.pods]perlmodinstall.pod [.lib.pods]perlmodlib.pod [.lib.pods]perlmodstyle.pod [.lib.pods]perlmpeix.pod [.lib.pods]perlmroapi.pod
+pod19 = [.lib.pods]perlnetware.pod [.lib.pods]perlnewmod.pod [.lib.pods]perlnumber.pod [.lib.pods]perlobj.pod [.lib.pods]perlop.pod
+pod20 = [.lib.pods]perlopenbsd.pod [.lib.pods]perlopentut.pod [.lib.pods]perlos2.pod [.lib.pods]perlos390.pod [.lib.pods]perlos400.pod
+pod21 = [.lib.pods]perlpacktut.pod [.lib.pods]perlperf.pod [.lib.pods]perlplan9.pod [.lib.pods]perlpod.pod [.lib.pods]perlpodspec.pod [.lib.pods]perlport.pod
+pod22 = [.lib.pods]perlpragma.pod [.lib.pods]perlqnx.pod [.lib.pods]perlre.pod [.lib.pods]perlreapi.pod [.lib.pods]perlrebackslash.pod
+pod23 = [.lib.pods]perlrecharclass.pod [.lib.pods]perlref.pod [.lib.pods]perlreftut.pod [.lib.pods]perlreguts.pod [.lib.pods]perlrepository.pod
+pod24 = [.lib.pods]perlrequick.pod [.lib.pods]perlreref.pod [.lib.pods]perlretut.pod [.lib.pods]perlriscos.pod [.lib.pods]perlrun.pod [.lib.pods]perlsec.pod
+pod25 = [.lib.pods]perlsolaris.pod [.lib.pods]perlstyle.pod [.lib.pods]perlsub.pod [.lib.pods]perlsymbian.pod [.lib.pods]perlsyn.pod
+pod26 = [.lib.pods]perlthrtut.pod [.lib.pods]perltie.pod [.lib.pods]perltoc.pod [.lib.pods]perltodo.pod [.lib.pods]perltooc.pod [.lib.pods]perltoot.pod
+pod27 = [.lib.pods]perltrap.pod [.lib.pods]perltru64.pod [.lib.pods]perltw.pod [.lib.pods]perlunicode.pod [.lib.pods]perlunifaq.pod
+pod28 = [.lib.pods]perluniintro.pod [.lib.pods]perlunitut.pod [.lib.pods]perlutil.pod [.lib.pods]perluts.pod [.lib.pods]perlvar.pod [.lib.pods]perlvmesa.pod
+pod29 = [.lib.pods]perlvms.pod [.lib.pods]perlvos.pod [.lib.pods]perlwin32.pod [.lib.pods]perlxs.pod [.lib.pods]perlxstut.pod
 pod = $(pod0) $(pod1) $(pod2) $(pod3) $(pod4) $(pod5) $(pod6) $(pod7) $(pod8) $(pod9) $(pod10) $(pod11) $(pod12) $(pod13) $(pod14) $(pod15) $(pod16) $(pod17) $(pod18) $(pod19) $(pod20) $(pod21) $(pod22) $(pod23) $(pod24) $(pod25) $(pod26) $(pod27) $(pod28) $(pod29)
 
 # Would be useful to automate the generation of this rule from pod/buildtoc
@@ -1162,6 +1162,10 @@ makeppport : $(MINIPERL_EXE) $(ARCHDIR)Config.pm
        @ If F$Search("[.lib]pods.dir").eqs."" Then Create/Directory [.lib.pods]
        Copy/NoConfirm/Log $(MMS$SOURCE) [.lib.pods]
 
+[.lib.pods]perlmroapi.pod : [.pod]perlmroapi.pod
+       @ If F$Search("[.lib]pods.dir").eqs."" Then Create/Directory [.lib.pods]
+       Copy/NoConfirm/Log $(MMS$SOURCE) [.lib.pods]
+
 [.lib.pods]perlnetware.pod : [.pod]perlnetware.pod
        @ If F$Search("[.lib]pods.dir").eqs."" Then Create/Directory [.lib.pods]
        Copy/NoConfirm/Log $(MMS$SOURCE) [.lib.pods]

diff --git a/win32/pod.mak b/win32/pod.mak
index 22e9618..cddd15c 100644 (file)
--- a/win32/pod.mak
+++ b/win32/pod.mak
@@ -94,6 +94,7 @@ POD = \
        perlmodinstall.pod      \
        perlmodlib.pod  \
        perlmodstyle.pod        \
+       perlmroapi.pod  \
        perlnewmod.pod  \
        perlnumber.pod  \
        perlobj.pod     \
@@ -218,6 +219,7 @@ MAN = \
        perlmodinstall.man      \
        perlmodlib.man  \
        perlmodstyle.man        \
+       perlmroapi.man  \
        perlnewmod.man  \
        perlnumber.man  \
        perlobj.man     \
@@ -342,6 +344,7 @@ HTML = \
        perlmodinstall.html     \
        perlmodlib.html \
        perlmodstyle.html       \
+       perlmroapi.html \
        perlnewmod.html \
        perlnumber.html \
        perlobj.html    \
@@ -466,6 +469,7 @@ TEX = \
        perlmodinstall.tex      \
        perlmodlib.tex  \
        perlmodstyle.tex        \
+       perlmroapi.tex  \
        perlnewmod.tex  \
        perlnumber.tex  \
        perlobj.tex     \