diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perlmroapi.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/pods/perlmroapi.pod | 94 |
1 files changed, 94 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/pods/perlmroapi.pod b/Master/tlpkg/tlperl/lib/pods/perlmroapi.pod new file mode 100644 index 00000000000..2200becded2 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/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 |