diff options
| -rw-r--r-- | MANIFEST | 1 | ||||
| -rw-r--r-- | pod.lst | 1 | ||||
| -rw-r--r-- | pod/perl.pod | 1 | ||||
| -rw-r--r-- | pod/perlmroapi.pod | 94 | ||||
| -rw-r--r-- | vms/descrip_mms.template | 28 | ||||
| -rw-r--r-- | win32/pod.mak | 4 |
6 files changed, 117 insertions, 12 deletions
@@ -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 @@ -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 d9c20d35ed..eaf9c591e5 100644 --- 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 index 0000000000..2200becded --- /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 d7d06158b4..edaacc0cca 100644 --- 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 22e9618fa4..cddd15c12a 100644 --- 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 \ |