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 | ||
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 | |
bc56db2a | 57 | classes in order. The names of the classes should be the result of calling |
2ffab098 FC |
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. | |
15932acc NC |
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 |