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