1=head1 NAME 2 3perlmroapi - Perl method resolution plugin interface 4 5=head1 DESCRIPTION 6 7As of Perl 5.10.1 there is a new interface for plugging and using method 8resolution orders other than the default (linear depth first search). 9The C3 method resolution order added in 5.10.0 has been re-implemented as 10a plugin, without changing its Perl-space interface. 11 12Each plugin should register itself by providing 13the following structure 14 15 struct mro_alg { 16 AV *(*resolve)(pTHX_ HV *stash, U32 level); 17 const char *name; 18 U16 length; 19 U16 kflags; 20 U32 hash; 21 }; 22 23and calling C<Perl_mro_register>: 24 25 Perl_mro_register(aTHX_ &my_mro_alg); 26 27=over 4 28 29=item resolve 30 31Pointer to the linearisation function, described below. 32 33=item name 34 35Name of the MRO, either in ISO-8859-1 or UTF-8. 36 37=item length 38 39Length of the name. 40 41=item kflags 42 43If the name is given in UTF-8, set this to C<HVhek_UTF8>. The value is passed 44direct as the parameter I<kflags> to C<hv_common()>. 45 46=item hash 47 48A precomputed hash value for the MRO's name, or 0. 49 50=back 51 52=head1 Callbacks 53 54The C<resolve> function is called to generate a linearised ISA for the 55given stash, using this MRO. It is called with a pointer to the stash, and 56a I<level> of 0. The core always sets I<level> to 0 when it calls your 57function - the parameter is provided to allow your implementation to track 58depth if it needs to recurse. 59 60The function should return a reference to an array containing the parent 61classes in order. The names of the classes should be the result of calling 62C<HvENAME()> on the stash. In those cases where C<HvENAME()> returns null, 63C<HvNAME()> should be used instead. 64 65The caller is responsible for incrementing the reference count of the array 66returned if it wants to keep the structure. Hence, if you have created a 67temporary value that you keep no pointer to, C<sv_2mortal()> to ensure that 68it is disposed of correctly. If you have cached your return value, then 69return a pointer to it without changing the reference count. 70 71=head1 Caching 72 73Computing MROs can be expensive. The implementation provides a cache, in 74which you can store a single C<SV *>, or anything that can be cast to 75C<SV *>, such as C<AV *>. To read your private value, use the macro 76C<MRO_GET_PRIVATE_DATA()>, passing it the C<mro_meta> structure from the 77stash, and a pointer to your C<mro_alg> structure: 78 79 meta = HvMROMETA(stash); 80 private_sv = MRO_GET_PRIVATE_DATA(meta, &my_mro_alg); 81 82=for apidoc mro_get_private_data 83 84To set your private value, call C<Perl_mro_set_private_data()>: 85 86 Perl_mro_set_private_data(aTHX_ meta, &c3_alg, private_sv); 87 88=for apidoc mro_set_private_data 89 90The private data cache will take ownership of a reference to private_sv, 91much the same way that C<hv_store()> takes ownership of a reference to the 92value that you pass it. 93 94=head1 Examples 95 96For examples of MRO implementations, see C<S_mro_get_linear_isa_c3()> 97and the C<BOOT:> section of F<ext/mro/mro.xs>, and 98C<S_mro_get_linear_isa_dfs()> in F<mro_core.c> 99 100=head1 AUTHORS 101 102The implementation of the C3 MRO and switchable MROs within the perl core was 103written by Brandon L Black. Nicholas Clark created the pluggable interface, 104refactored Brandon's implementation to work with it, and wrote this document. 105 106=cut 107