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