Add documentation for the method resolution plugin interface.
authorNicholas Clark <nick@ccl4.org>
Thu, 25 Jun 2009 15:04:37 +0000 (16:04 +0100)
committerDavid Mitchell <davem@iabyn.com>
Sat, 27 Jun 2009 16:41:48 +0000 (17:41 +0100)
(cherry-picked from commit 15932acc618e3c642a4814dee6429b92b088b3fd)

MANIFEST
pod.lst
pod/perl.pod
pod/perlmroapi.pod [new file with mode: 0644]
vms/descrip_mms.template
win32/pod.mak

index a548195..bd285c9 100755 (executable)
--- a/MANIFEST
+++ b/MANIFEST
@@ -3634,6 +3634,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 be6141e..de32a96 100644 (file)
--- a/pod.lst
+++ b/pod.lst
@@ -113,6 +113,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
 
index 64dd9a0..939c683 100644 (file)
@@ -128,6 +128,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
@@ -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
index c668d36..6f1b037 100644 (file)
@@ -418,9 +418,9 @@ 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]perlothrtut.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 [.lib.pods]perlothrtut.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
@@ -1163,6 +1163,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]
index 26ff52e..3c94557 100644 (file)
@@ -94,6 +94,7 @@ POD = \
        perlmodinstall.pod      \
        perlmodlib.pod  \
        perlmodstyle.pod        \
+       perlmroapi.pod  \
        perlnewmod.pod  \
        perlnumber.pod  \
        perlobj.pod     \
@@ -219,6 +220,7 @@ MAN = \
        perlmodinstall.man      \
        perlmodlib.man  \
        perlmodstyle.man        \
+       perlmroapi.man  \
        perlnewmod.man  \
        perlnumber.man  \
        perlobj.man     \
@@ -344,6 +346,7 @@ HTML = \
        perlmodinstall.html     \
        perlmodlib.html \
        perlmodstyle.html       \
+       perlmroapi.html \
        perlnewmod.html \
        perlnumber.html \
        perlobj.html    \
@@ -469,6 +472,7 @@ TEX = \
        perlmodinstall.tex      \
        perlmodlib.tex  \
        perlmodstyle.tex        \
+       perlmroapi.tex  \
        perlnewmod.tex  \
        perlnumber.tex  \
        perlobj.tex     \