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.
38 These interfaces are only available in Perl 5.9.5 and higher.
39 See L<MRO::Compat> on CPAN for a mostly forwards compatible
40 implementation for older Perls.
44 It's possible to change the MRO of a given class either by using C<use
45 mro> as shown in the synopsis, or by using the L</mro::set_mro> function
46 below. The functions do not require loading the C<mro> module, as they
47 are actually provided by the core perl interpreter. The C<use mro> syntax
48 is just syntactic sugar for setting the current package's MRO.
52 In addition to the traditional Perl default MRO (depth first
53 search, called C<DFS> here), Perl now offers the C3 MRO as
54 well. Perl's support for C3 is based on the work done in
55 Stevan Little's module L<Class::C3>, and most of the C3-related
56 documentation here is ripped directly from there.
60 C3 is the name of an algorithm which aims to provide a sane method
61 resolution order under multiple inheritance. It was first introduced in
62 the language Dylan (see links in the L</"SEE ALSO"> section), and then
63 later adopted as the preferred MRO (Method Resolution Order) for the
64 new-style classes in Python 2.3. Most recently it has been adopted as the
65 "canonical" MRO for Perl 6 classes, and the default MRO for Parrot objects
68 =head2 How does C3 work
70 C3 works by always preserving local precendence ordering. This essentially
71 means that no class will appear before any of its subclasses. Take, for
72 instance, the classic diamond inheritance pattern:
80 The standard Perl 5 MRO would be (D, B, A, C). The result being that B<A>
81 appears before B<C>, even though B<C> is the subclass of B<A>. The C3 MRO
82 algorithm however, produces the following order: (D, B, C, A), which does
85 This example is fairly trivial; for more complex cases and a deeper
86 explanation, see the links in the L</"SEE ALSO"> section.
90 =head2 mro::get_linear_isa($classname[, $type])
92 Returns an arrayref which is the linearized MRO of the given class.
93 Uses whichever MRO is currently in effect for that class by default,
94 or the given MRO (either C<c3> or C<dfs> if specified as C<$type>).
96 The linearized MRO of a class is an ordered array of all of the
97 classes one would search when resolving a method on that class,
98 starting with the class itself.
100 If the requested class doesn't yet exist, this function will still
101 succeed, and return C<[ $classname ]>
103 Note that C<UNIVERSAL> (and any members of C<UNIVERSAL>'s MRO) are not
104 part of the MRO of a class, even though all classes implicitly inherit
105 methods from C<UNIVERSAL> and its parents.
107 =head2 mro::set_mro($classname, $type)
109 Sets the MRO of the given class to the C<$type> argument (either
112 =head2 mro::get_mro($classname)
114 Returns the MRO of the given class (either C<c3> or C<dfs>).
116 =head2 mro::get_isarev($classname)
118 Gets the C<mro_isarev> for this class, returned as an
119 arrayref of class names. These are every class that "isa"
120 the given class name, even if the isa relationship is
121 indirect. This is used internally by the MRO code to
122 keep track of method/MRO cache invalidations.
124 Currently, this list only grows, it never shrinks. This
125 was a performance consideration (properly tracking and
126 deleting isarev entries when someone removes an entry
127 from an C<@ISA> is costly, and it doesn't happen often
128 anyways). The fact that a class which no longer truly
129 "isa" this class at runtime remains on the list should be
130 considered a quirky implementation detail which is subject
131 to future change. It shouldn't be an issue as long as
132 you're looking at this list for the same reasons the
133 core code does: as a performance optimization
134 over having to search every class in existence.
136 As with C<mro::get_mro> above, C<UNIVERSAL> is special.
137 C<UNIVERSAL> (and parents') isarev lists do not include
138 every class in existence, even though all classes are
139 effectively descendants for method inheritance purposes.
141 =head2 mro::is_universal($classname)
143 Returns a boolean status indicating whether or not
144 the given classname is either C<UNIVERSAL> itself,
145 or one of C<UNIVERSAL>'s parents by C<@ISA> inheritance.
147 Any class for which this function returns true is
148 "universal" in the sense that all classes potentially
149 inherit methods from it.
151 For similar reasons to C<isarev> above, this flag is
152 permanent. Once it is set, it does not go away, even
153 if the class in question really isn't universal anymore.
155 =head2 mro::invalidate_all_method_caches()
157 Increments C<PL_sub_generation>, which invalidates method
158 caching in all packages.
160 =head2 mro::method_changed_in($classname)
162 Invalidates the method cache of any classes dependent on the
163 given class. This is not normally necessary. The only
164 known case where pure perl code can confuse the method
165 cache is when you manually install a new constant
166 subroutine by using a readonly scalar value, like the
167 internals of L<constant> do. If you find another case,
168 please report it so we can either fix it or document
171 =head2 mro::get_pkg_gen($classname)
173 Returns an integer which is incremented every time a
174 real local method in the package C<$classname> changes,
175 or the local C<@ISA> of C<$classname> is modified.
177 This is intended for authors of modules which do lots
178 of class introspection, as it allows them to very quickly
179 check if anything important about the local properties
180 of a given class have changed since the last time they
181 looked. It does not increment on method/C<@ISA>
182 changes in superclasses.
184 It's still up to you to seek out the actual changes,
185 and there might not actually be any. Perhaps all
186 of the changes since you last checked cancelled each
187 other out and left the package in the state it was in
190 This integer normally starts off at a value of C<1>
191 when a package stash is instantiated. Calling it
192 on packages whose stashes do not exist at all will
193 return C<0>. If a package stash is completely
194 deleted (not a normal occurence, but it can happen
195 if someone does something like C<undef %PkgName::>),
196 the number will be reset to either C<0> or C<1>,
197 depending on how completely package was wiped out.
201 This is somewhat like C<SUPER>, but it uses the C3 method
202 resolution order to get better consistency in multiple
203 inheritance situations. Note that while inheritance in
204 general follows whichever MRO is in effect for the
205 given class, C<next::method> only uses the C3 MRO.
207 One generally uses it like so:
211 my $superclass_answer = $self->next::method(@_);
212 return $superclass_answer + 1;
215 Note that you don't (re-)specify the method name.
216 It forces you to always use the same method name
217 as the method you started in.
219 It can be called on an object or a class, of course.
221 The way it resolves which actual method to call is:
227 First, it determines the linearized C3 MRO of
228 the object or class it is being called on.
232 Then, it determines the class and method name
233 of the context it was invoked from.
237 Finally, it searches down the C3 MRO list until
238 it reaches the contextually enclosing class, then
239 searches further down the MRO list for the next
240 method with the same name as the contextually
245 Failure to find a next method will result in an
246 exception being thrown (see below for alternatives).
248 This is substantially different than the behavior
249 of C<SUPER> under complex multiple inheritance.
250 (This becomes obvious when one realizes that the
251 common superclasses in the C3 linearizations of
252 a given class and one of its parents will not
253 always be ordered the same for both.)
255 B<Caveat>: Calling C<next::method> from methods defined outside the class:
257 There is an edge case when using C<next::method> from within a subroutine
258 which was created in a different module than the one it is called from. It
259 sounds complicated, but it really isn't. Here is an example which will not
262 *Foo::foo = sub { (shift)->next::method(@_) };
264 The problem exists because the anonymous subroutine being assigned to the
265 C<*Foo::foo> glob will show up in the call stack as being called
266 C<__ANON__> and not C<foo> as you might expect. Since C<next::method> uses
267 C<caller> to find the name of the method it was called in, it will fail in
270 But fear not, there's a simple solution. The module C<Sub::Name> will
271 reach into the perl internals and assign a name to an anonymous subroutine
272 for you. Simply do this:
274 use Sub::Name 'subname';
275 *Foo::foo = subname 'Foo::foo' => sub { (shift)->next::method(@_) };
277 and things will Just Work.
281 This is similar to C<next::method>, but just returns either a code
282 reference or C<undef> to indicate that no further methods of this name
285 =head2 maybe::next::method
287 In simple cases, it is equivalent to:
289 $self->next::method(@_) if $self->next_can;
291 But there are some cases where only this solution
292 works (like C<goto &maybe::next::method>);
294 =head1 PERFORMANCE CONSIDERATIONS
296 Specifying the mro type of a class before setting C<@ISA> will
297 be faster than the other way around. Also, making all of your
298 C<@ISA> manipulations in a single assignment statement will be
299 faster that doing them one by one via C<push> (which is what
300 C<use base> does currently).
310 # (not exactly equivalent to above,
311 # as base.pm can do other magic)
316 our @ISA = qw/A B C/;
318 Generally speaking, every time C<@ISA> is modified, the MRO
319 of that class will be recalculated, because of the way array
320 magic works. Pushing multiple items onto C<@ISA> in one push
321 statement still counts as multiple modifications. However,
322 assigning a list to C<@ISA> only counts as a single
323 modification. Thus if you really need to do C<push> as
324 opposed to assignment, C<@ISA = (@ISA, qw/A B C/);>
325 will still be faster than C<push(@ISA, qw/A B C/);>
329 =head2 The original Dylan paper
333 =item L<http://www.webcom.com/haahr/dylan/linearization-oopsla96.html>
337 =head2 The prototype Perl 6 Object Model uses C3
341 =item L<http://svn.openfoundry.org/pugs/perl5/Perl6-MetaModel/>
345 =head2 Parrot now uses C3
349 =item L<http://aspn.activestate.com/ASPN/Mail/Message/perl6-internals/2746631>
351 =item L<http://use.perl.org/~autrijus/journal/25768>
355 =head2 Python 2.3 MRO related links
359 =item L<http://www.python.org/2.3/mro.html>
361 =item L<http://www.python.org/2.2.2/descrintro.html#mro>
365 =head2 C3 for TinyCLOS
369 =item L<http://www.call-with-current-continuation.org/eggs/c3.html>
383 Brandon L. Black, E<lt>blblack@gmail.comE<gt>
385 Based on Stevan Little's L<Class::C3>