3 # Copyright (c) 2007 Brandon L Black
5 # You may distribute under the terms of either the GNU General Public
6 # License or the Artistic License, as specified in the README file.
12 # mro.pm versions < 1.00 reserved for possible CPAN mro dist
13 # (for partial back-compat to 5.[68].x)
14 our $VERSION = '1.00';
17 mro::set_mro(scalar(caller), $_[1]) if $_[1];
26 mro - Method Resolution Order
30 use mro 'dfs'; # enable DFS MRO for this class (Perl default)
31 use mro 'c3'; # enable C3 MRO for this class
35 The "mro" namespace provides several utilities for dealing
36 with method resolution order and method caching in general.
40 It's possible to change the MRO of a given class either by using C<use
41 mro> as shown in the synopsis, or by using the L</mro::set_mro> function
42 below. The functions do not require loading the C<mro> module, as they
43 are actually provided by the core perl interpreter. The C<use mro> syntax
44 is just syntactic sugar for setting the current package's MRO.
48 In addition to the traditional Perl default MRO (depth first
49 search, called C<DFS> here), Perl now offers the C3 MRO as
50 well. Perl's support for C3 is based on the work done in
51 Stevan Little's module L<Class::C3>, and most of the C3-related
52 documentation here is ripped directly from there.
56 C3 is the name of an algorithm which aims to provide a sane method
57 resolution order under multiple inheritance. It was first introduced in
58 the language Dylan (see links in the L</"SEE ALSO"> section), and then
59 later adopted as the preferred MRO (Method Resolution Order) for the
60 new-style classes in Python 2.3. Most recently it has been adopted as the
61 "canonical" MRO for Perl 6 classes, and the default MRO for Parrot objects
64 =head2 How does C3 work
66 C3 works by always preserving local precendence ordering. This essentially
67 means that no class will appear before any of its subclasses. Take, for
68 instance, the classic diamond inheritance pattern:
76 The standard Perl 5 MRO would be (D, B, A, C). The result being that B<A>
77 appears before B<C>, even though B<C> is the subclass of B<A>. The C3 MRO
78 algorithm however, produces the following order: (D, B, C, A), which does
81 This example is fairly trivial; for more complex cases and a deeper
82 explanation, see the links in the L</"SEE ALSO"> section.
86 =head2 mro::get_linear_isa($classname[, $type])
88 Returns an arrayref which is the linearized MRO of the given class.
89 Uses whichever MRO is currently in effect for that class by default,
90 or the given MRO (either C<c3> or C<dfs> if specified as C<$type>).
92 Note that C<UNIVERSAL> (and any members of C<UNIVERSAL>'s MRO) are not
93 part of the MRO of a class, even though all classes implicitly inherit
94 methods from C<UNIVERSAL> and its parents.
96 =head2 mro::set_mro($classname, $type)
98 Sets the MRO of the given class to the C<$type> argument (either
101 =head2 mro::get_mro($classname)
103 Returns the MRO of the given class (either C<c3> or C<dfs>).
105 =head2 mro::get_isarev($classname)
107 Gets the C<mro_isarev> for this class, returned as an
108 array of class names. These are every class that "isa"
109 the given class name, even if the isa relationship is
110 indirect. This is used internally by the MRO code to
111 keep track of method/MRO cache invalidations.
113 Currently, this list only grows, it never shrinks. This
114 was a performance consideration (properly tracking and
115 deleting isarev entries when someone removes an entry
116 from an C<@ISA> is costly, and it doesn't happen often
117 anyways). The fact that a class which no longer truly
118 "isa" this class at runtime remains on the list should be
119 considered a quirky implementation detail which is subject
120 to future change. It shouldn't be an issue as long as
121 you're looking at this list for the same reasons the
122 core code does: as a performance optimization
123 over having to search every class in existence.
125 As with C<mro::get_mro> above, C<UNIVERSAL> is special.
126 C<UNIVERSAL> (and parents') isarev lists do not include
127 every class in existence, even though all classes are
128 effectively descendants for method inheritance purposes.
130 =head2 mro::is_universal($classname)
132 Returns a boolean status indicating whether or not
133 the given classname is either C<UNIVERSAL> itself,
134 or one of C<UNIVERSAL>'s parents by C<@ISA> inheritance.
136 Any class for which this function returns true is
137 "universal" in the sense that all classes potentially
138 inherit methods from it.
140 For similar reasons to C<isarev> above, this flag is
141 permanent. Once it is set, it does not go away, even
142 if the class in question really isn't universal anymore.
144 =head2 mro::invalidate_all_method_caches()
146 Increments C<PL_sub_generation>, which invalidates method
147 caching in all packages.
149 =head2 mro::method_changed_in($classname)
151 Invalidates the method cache of any classes dependent on the
156 This is somewhat like C<SUPER>, but it uses the C3 method
157 resolution order to get better consistency in multiple
158 inheritance situations. Note that while inheritance in
159 general follows whichever MRO is in effect for the
160 given class, C<next::method> only uses the C3 MRO.
162 One generally uses it like so:
166 my $superclass_answer = $self->next::method(@_);
167 return $superclass_answer + 1;
170 Note that you don't (re-)specify the method name.
171 It forces you to always use the same method name
172 as the method you started in.
174 It can be called on an object or a class, of course.
176 The way it resolves which actual method to call is:
182 First, it determines the linearized C3 MRO of
183 the object or class it is being called on.
187 Then, it determines the class and method name
188 of the context it was invoked from.
192 Finally, it searches down the C3 MRO list until
193 it reaches the contextually enclosing class, then
194 searches further down the MRO list for the next
195 method with the same name as the contextually
200 Failure to find a next method will result in an
201 exception being thrown (see below for alternatives).
203 This is substantially different than the behavior
204 of C<SUPER> under complex multiple inheritance.
205 (This becomes obvious when one realizes that the
206 common superclasses in the C3 linearizations of
207 a given class and one of its parents will not
208 always be ordered the same for both.)
210 B<Caveat>: Calling C<next::method> from methods defined outside the class:
212 There is an edge case when using C<next::method> from within a subroutine
213 which was created in a different module than the one it is called from. It
214 sounds complicated, but it really isn't. Here is an example which will not
217 *Foo::foo = sub { (shift)->next::method(@_) };
219 The problem exists because the anonymous subroutine being assigned to the
220 C<*Foo::foo> glob will show up in the call stack as being called
221 C<__ANON__> and not C<foo> as you might expect. Since C<next::method> uses
222 C<caller> to find the name of the method it was called in, it will fail in
225 But fear not, there's a simple solution. The module C<Sub::Name> will
226 reach into the perl internals and assign a name to an anonymous subroutine
227 for you. Simply do this:
229 use Sub::Name 'subname';
230 *Foo::foo = subname 'Foo::foo' => sub { (shift)->next::method(@_) };
232 and things will Just Work.
236 This is similar to C<next::method>, but just returns either a code
237 reference or C<undef> to indicate that no further methods of this name
240 =head2 maybe::next::method
242 In simple cases, it is equivalent to:
244 $self->next::method(@_) if $self->next_can;
246 But there are some cases where only this solution
247 works (like C<goto &maybe::next::method>);
251 =head2 The original Dylan paper
255 =item L<http://www.webcom.com/haahr/dylan/linearization-oopsla96.html>
259 =head2 The prototype Perl 6 Object Model uses C3
263 =item L<http://svn.openfoundry.org/pugs/perl5/Perl6-MetaModel/>
267 =head2 Parrot now uses C3
271 =item L<http://aspn.activestate.com/ASPN/Mail/Message/perl6-internals/2746631>
273 =item L<http://use.perl.org/~autrijus/journal/25768>
277 =head2 Python 2.3 MRO related links
281 =item L<http://www.python.org/2.3/mro.html>
283 =item L<http://www.python.org/2.2.2/descrintro.html#mro>
287 =head2 C3 for TinyCLOS
291 =item L<http://www.call-with-current-continuation.org/eggs/c3.html>
305 Brandon L. Black, E<lt>blblack@gmail.comE<gt>
307 Based on Stevan Little's L<Class::C3>