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 | |
57 | classes in order. The caller is responsible for incrementing the reference | |
58 | count if it wants to keep the structure. Hence if you have created a | |
59 | temporary value that you keep no pointer to, C<sv_2mortal()> to ensure that | |
60 | it is disposed of correctly. If you have cached your return value, then | |
61 | return a pointer to it without changing the reference count. | |
62 | ||
63 | =head1 Caching | |
64 | ||
65 | Computing MROs can be expensive. The implementation provides a cache, in | |
66 | which you can store a single C<SV *>, or anything that can be cast to | |
67 | C<SV *>, such as C<AV *>. To read your private value, use the macro | |
68 | C<MRO_GET_PRIVATE_DATA()>, passing it the C<mro_meta> structure from the | |
69 | stash, and a pointer to your C<mro_alg> structure: | |
70 | ||
71 | meta = HvMROMETA(stash); | |
72 | private_sv = MRO_GET_PRIVATE_DATA(meta, &my_mro_alg); | |
73 | ||
74 | To set your private value, call C<Perl_mro_set_private_data()>: | |
75 | ||
76 | Perl_mro_set_private_data(aTHX_ meta, &c3_alg, private_sv); | |
77 | ||
78 | The private data cache will take ownership of a reference to private_sv, | |
79 | much the same way that C<hv_store()> takes ownership of a reference to the | |
80 | value that you pass it. | |
81 | ||
82 | =head1 Examples | |
83 | ||
84 | For examples of MRO implementations, see C<S_mro_get_linear_isa_c3()> | |
85 | and the C<BOOT:> section of F<mro/mro.xs>, and C<S_mro_get_linear_isa_dfs()> | |
86 | in F<mro.c> | |
87 | ||
88 | =head1 AUTHORS | |
89 | ||
90 | The implementation of the C3 MRO and switchable MROs within the perl core was | |
91 | written by Brandon L Black. Nicholas Clark created the pluggable interface, | |
92 | refactored Brandon's implementation to work with it, and wrote this document. | |
93 | ||
94 | =cut |