This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Increase $mro::VERSION to 1.13
[perl5.git] / ext / mro / mro.pm
CommitLineData
e1a479c5
BB
1# mro.pm
2#
3# Copyright (c) 2007 Brandon L Black
dc275821 4# Copyright (c) 2008,2009 Larry Wall and others
e1a479c5
BB
5#
6# You may distribute under the terms of either the GNU General Public
7# License or the Artistic License, as specified in the README file.
8#
9package mro;
10use strict;
11use warnings;
12
f58cd386
BB
13# mro.pm versions < 1.00 reserved for MRO::Compat
14# for partial back-compat to 5.[68].x
57702e88 15our $VERSION = '1.13';
e1a479c5
BB
16
17sub import {
18 mro::set_mro(scalar(caller), $_[1]) if $_[1];
19}
20
f58cd386
BB
21package # hide me from PAUSE
22 next;
23
24sub can { mro::_nextcan($_[0], 0) }
25
26sub method {
27 my $method = mro::_nextcan($_[0], 1);
28 goto &$method;
29}
30
31package # hide me from PAUSE
32 maybe::next;
33
34sub method {
35 my $method = mro::_nextcan($_[0], 0);
36 goto &$method if defined $method;
37 return;
38}
39
b2685f0c 40require XSLoader;
da4061d3 41XSLoader::load('mro');
b2685f0c 42
e1a479c5
BB
431;
44
45__END__
46
47=head1 NAME
48
49mro - Method Resolution Order
50
51=head1 SYNOPSIS
52
f58cd386
BB
53 use mro; # enables next::method and friends globally
54
2e4b0c4a
RGS
55 use mro 'dfs'; # enable DFS MRO for this class (Perl default)
56 use mro 'c3'; # enable C3 MRO for this class
e1a479c5
BB
57
58=head1 DESCRIPTION
59
60The "mro" namespace provides several utilities for dealing
61with method resolution order and method caching in general.
62
70cd14a1
CB
63These interfaces are only available in Perl 5.9.5 and higher.
64See L<MRO::Compat> on CPAN for a mostly forwards compatible
65implementation for older Perls.
66
e1a479c5
BB
67=head1 OVERVIEW
68
2e4b0c4a
RGS
69It's possible to change the MRO of a given class either by using C<use
70mro> as shown in the synopsis, or by using the L</mro::set_mro> function
58d4c5df 71below.
f58cd386
BB
72
73The special methods C<next::method>, C<next::can>, and
74C<maybe::next::method> are not available until this C<mro> module
75has been loaded via C<use> or C<require>.
e1a479c5
BB
76
77=head1 The C3 MRO
78
79In addition to the traditional Perl default MRO (depth first
2e4b0c4a 80search, called C<DFS> here), Perl now offers the C3 MRO as
e1a479c5 81well. Perl's support for C3 is based on the work done in
2e4b0c4a 82Stevan Little's module L<Class::C3>, and most of the C3-related
e1a479c5
BB
83documentation here is ripped directly from there.
84
85=head2 What is C3?
86
2e4b0c4a
RGS
87C3 is the name of an algorithm which aims to provide a sane method
88resolution order under multiple inheritance. It was first introduced in
89the language Dylan (see links in the L</"SEE ALSO"> section), and then
90later adopted as the preferred MRO (Method Resolution Order) for the
91new-style classes in Python 2.3. Most recently it has been adopted as the
92"canonical" MRO for Perl 6 classes, and the default MRO for Parrot objects
93as well.
e1a479c5 94
2e4b0c4a 95=head2 How does C3 work
e1a479c5 96
98ccfbbf 97C3 works by always preserving local precedence ordering. This essentially
2e4b0c4a
RGS
98means that no class will appear before any of its subclasses. Take, for
99instance, the classic diamond inheritance pattern:
e1a479c5
BB
100
101 <A>
102 / \
103 <B> <C>
104 \ /
105 <D>
106
2e4b0c4a
RGS
107The standard Perl 5 MRO would be (D, B, A, C). The result being that B<A>
108appears before B<C>, even though B<C> is the subclass of B<A>. The C3 MRO
109algorithm however, produces the following order: (D, B, C, A), which does
110not have this issue.
e1a479c5 111
2e4b0c4a
RGS
112This example is fairly trivial; for more complex cases and a deeper
113explanation, see the links in the L</"SEE ALSO"> section.
e1a479c5
BB
114
115=head1 Functions
116
2e4b0c4a 117=head2 mro::get_linear_isa($classname[, $type])
e1a479c5 118
2e4b0c4a 119Returns an arrayref which is the linearized MRO of the given class.
e1a479c5 120Uses whichever MRO is currently in effect for that class by default,
2e4b0c4a 121or the given MRO (either C<c3> or C<dfs> if specified as C<$type>).
e1a479c5 122
70cd14a1
CB
123The linearized MRO of a class is an ordered array of all of the
124classes one would search when resolving a method on that class,
125starting with the class itself.
126
127If the requested class doesn't yet exist, this function will still
128succeed, and return C<[ $classname ]>
129
2e4b0c4a
RGS
130Note that C<UNIVERSAL> (and any members of C<UNIVERSAL>'s MRO) are not
131part of the MRO of a class, even though all classes implicitly inherit
e1a479c5
BB
132methods from C<UNIVERSAL> and its parents.
133
345e2394 134=head2 mro::set_mro ($classname, $type)
e1a479c5 135
2e4b0c4a 136Sets the MRO of the given class to the C<$type> argument (either
e1a479c5
BB
137C<c3> or C<dfs>).
138
2e4b0c4a 139=head2 mro::get_mro($classname)
e1a479c5 140
2e4b0c4a 141Returns the MRO of the given class (either C<c3> or C<dfs>).
e1a479c5 142
2e4b0c4a 143=head2 mro::get_isarev($classname)
e1a479c5
BB
144
145Gets the C<mro_isarev> for this class, returned as an
70cd14a1 146arrayref of class names. These are every class that "isa"
2e4b0c4a
RGS
147the given class name, even if the isa relationship is
148indirect. This is used internally by the MRO code to
149keep track of method/MRO cache invalidations.
e1a479c5 150
6c1da365 151As with C<mro::get_linear_isa> above, C<UNIVERSAL> is special.
e1a479c5
BB
152C<UNIVERSAL> (and parents') isarev lists do not include
153every class in existence, even though all classes are
154effectively descendants for method inheritance purposes.
155
2e4b0c4a 156=head2 mro::is_universal($classname)
e1a479c5
BB
157
158Returns a boolean status indicating whether or not
159the given classname is either C<UNIVERSAL> itself,
160or one of C<UNIVERSAL>'s parents by C<@ISA> inheritance.
161
162Any class for which this function returns true is
163"universal" in the sense that all classes potentially
164inherit methods from it.
165
2e4b0c4a 166=head2 mro::invalidate_all_method_caches()
e1a479c5
BB
167
168Increments C<PL_sub_generation>, which invalidates method
169caching in all packages.
170
2e4b0c4a 171=head2 mro::method_changed_in($classname)
e1a479c5 172
2e4b0c4a 173Invalidates the method cache of any classes dependent on the
70cd14a1
CB
174given class. This is not normally necessary. The only
175known case where pure perl code can confuse the method
176cache is when you manually install a new constant
177subroutine by using a readonly scalar value, like the
178internals of L<constant> do. If you find another case,
179please report it so we can either fix it or document
180the exception here.
181
182=head2 mro::get_pkg_gen($classname)
183
184Returns an integer which is incremented every time a
185real local method in the package C<$classname> changes,
186or the local C<@ISA> of C<$classname> is modified.
187
188This is intended for authors of modules which do lots
189of class introspection, as it allows them to very quickly
190check if anything important about the local properties
191of a given class have changed since the last time they
192looked. It does not increment on method/C<@ISA>
193changes in superclasses.
194
195It's still up to you to seek out the actual changes,
196and there might not actually be any. Perhaps all
197of the changes since you last checked cancelled each
198other out and left the package in the state it was in
199before.
200
201This integer normally starts off at a value of C<1>
202when a package stash is instantiated. Calling it
203on packages whose stashes do not exist at all will
204return C<0>. If a package stash is completely
837cf3a0 205deleted (not a normal occurrence, but it can happen
70cd14a1
CB
206if someone does something like C<undef %PkgName::>),
207the number will be reset to either C<0> or C<1>,
17c7711f 208depending on how completely the package was wiped out.
e1a479c5
BB
209
210=head2 next::method
211
212This is somewhat like C<SUPER>, but it uses the C3 method
213resolution order to get better consistency in multiple
214inheritance situations. Note that while inheritance in
215general follows whichever MRO is in effect for the
216given class, C<next::method> only uses the C3 MRO.
217
218One generally uses it like so:
219
220 sub some_method {
221 my $self = shift;
e1a479c5
BB
222 my $superclass_answer = $self->next::method(@_);
223 return $superclass_answer + 1;
224 }
225
226Note that you don't (re-)specify the method name.
227It forces you to always use the same method name
228as the method you started in.
229
230It can be called on an object or a class, of course.
231
232The way it resolves which actual method to call is:
233
2e4b0c4a
RGS
234=over 4
235
236=item 1
237
238First, it determines the linearized C3 MRO of
e1a479c5
BB
239the object or class it is being called on.
240
2e4b0c4a
RGS
241=item 2
242
243Then, it determines the class and method name
e1a479c5
BB
244of the context it was invoked from.
245
2e4b0c4a
RGS
246=item 3
247
248Finally, it searches down the C3 MRO list until
e1a479c5
BB
249it reaches the contextually enclosing class, then
250searches further down the MRO list for the next
251method with the same name as the contextually
252enclosing method.
253
2e4b0c4a
RGS
254=back
255
e1a479c5
BB
256Failure to find a next method will result in an
257exception being thrown (see below for alternatives).
258
259This is substantially different than the behavior
2e4b0c4a
RGS
260of C<SUPER> under complex multiple inheritance.
261(This becomes obvious when one realizes that the
e1a479c5
BB
262common superclasses in the C3 linearizations of
263a given class and one of its parents will not
2e4b0c4a 264always be ordered the same for both.)
e1a479c5 265
2e4b0c4a 266B<Caveat>: Calling C<next::method> from methods defined outside the class:
e1a479c5 267
2e4b0c4a
RGS
268There is an edge case when using C<next::method> from within a subroutine
269which was created in a different module than the one it is called from. It
270sounds complicated, but it really isn't. Here is an example which will not
271work correctly:
e1a479c5
BB
272
273 *Foo::foo = sub { (shift)->next::method(@_) };
274
2e4b0c4a
RGS
275The problem exists because the anonymous subroutine being assigned to the
276C<*Foo::foo> glob will show up in the call stack as being called
277C<__ANON__> and not C<foo> as you might expect. Since C<next::method> uses
278C<caller> to find the name of the method it was called in, it will fail in
279this case.
280
281But fear not, there's a simple solution. The module C<Sub::Name> will
282reach into the perl internals and assign a name to an anonymous subroutine
283for you. Simply do this:
e1a479c5 284
e1a479c5
BB
285 use Sub::Name 'subname';
286 *Foo::foo = subname 'Foo::foo' => sub { (shift)->next::method(@_) };
287
288and things will Just Work.
289
290=head2 next::can
291
2e4b0c4a
RGS
292This is similar to C<next::method>, but just returns either a code
293reference or C<undef> to indicate that no further methods of this name
294exist.
e1a479c5
BB
295
296=head2 maybe::next::method
297
2e4b0c4a 298In simple cases, it is equivalent to:
e1a479c5 299
76051f89 300 $self->next::method(@_) if $self->next::can;
e1a479c5
BB
301
302But there are some cases where only this solution
2e4b0c4a 303works (like C<goto &maybe::next::method>);
e1a479c5 304
2e4b0c4a 305=head1 SEE ALSO
e1a479c5
BB
306
307=head2 The original Dylan paper
308
309=over 4
310
09c3cef4 311=item L<http://haahr.tempdomainname.com/dylan/linearization-oopsla96.html>
e1a479c5
BB
312
313=back
314
345e2394 315=head2 Pugs
e1a479c5 316
345e2394
JV
317The Pugs prototype Perl 6 Object Model uses C3
318
319=head2 Parrot
320
321Parrot now uses C3
e1a479c5
BB
322
323=over 4
324
e1a479c5
BB
325=item L<http://use.perl.org/~autrijus/journal/25768>
326
327=back
328
329=head2 Python 2.3 MRO related links
330
331=over 4
332
333=item L<http://www.python.org/2.3/mro.html>
334
335=item L<http://www.python.org/2.2.2/descrintro.html#mro>
336
337=back
338
e1a479c5
BB
339=head2 Class::C3
340
341=over 4
342
343=item L<Class::C3>
344
345=back
346
347=head1 AUTHOR
348
349Brandon L. Black, E<lt>blblack@gmail.comE<gt>
350
351Based on Stevan Little's L<Class::C3>
352
353=cut