| =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 by providing |
| the following structure |
| |
| struct mro_alg { |
| AV *(*resolve)(pTHX_ HV *stash, U32 level); |
| const char *name; |
| U16 length; |
| U16 kflags; |
| U32 hash; |
| }; |
| |
| and calling C<Perl_mro_register>: |
| |
| Perl_mro_register(aTHX_ &my_mro_alg); |
| |
| =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 names of the classes should be the result of calling |
| C<HvENAME()> on the stash. In those cases where C<HvENAME()> returns null, |
| C<HvNAME()> should be used instead. |
| |
| The caller is responsible for incrementing the reference count of the array |
| returned 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 |