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