3 # Copyright (c) 2007 Brandon L Black
4 # Copyright (c) 2008 Larry Wall and others
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.
13 # mro.pm versions < 1.00 reserved for MRO::Compat
14 # for partial back-compat to 5.[68].x
15 our $VERSION = '1.01';
18 mro::set_mro(scalar(caller), $_[1]) if $_[1];
21 package # hide me from PAUSE
24 sub can { mro::_nextcan($_[0], 0) }
27 my $method = mro::_nextcan($_[0], 1);
31 package # hide me from PAUSE
35 my $method = mro::_nextcan($_[0], 0);
36 goto &$method if defined $method;
41 XSLoader::load('mro', $VERSION);
49 mro - Method Resolution Order
53 use mro; # enables next::method and friends globally
55 use mro 'dfs'; # enable DFS MRO for this class (Perl default)
56 use mro 'c3'; # enable C3 MRO for this class
60 The "mro" namespace provides several utilities for dealing
61 with method resolution order and method caching in general.
63 These interfaces are only available in Perl 5.9.5 and higher.
64 See L<MRO::Compat> on CPAN for a mostly forwards compatible
65 implementation for older Perls.
69 It's possible to change the MRO of a given class either by using C<use
70 mro> as shown in the synopsis, or by using the L</mro::set_mro> function
71 below. The functions in the mro namespace do not require loading the
72 C<mro> module, as they are actually provided by the core perl interpreter.
74 The special methods C<next::method>, C<next::can>, and
75 C<maybe::next::method> are not available until this C<mro> module
76 has been loaded via C<use> or C<require>.
80 In addition to the traditional Perl default MRO (depth first
81 search, called C<DFS> here), Perl now offers the C3 MRO as
82 well. Perl's support for C3 is based on the work done in
83 Stevan Little's module L<Class::C3>, and most of the C3-related
84 documentation here is ripped directly from there.
88 C3 is the name of an algorithm which aims to provide a sane method
89 resolution order under multiple inheritance. It was first introduced in
90 the language Dylan (see links in the L</"SEE ALSO"> section), and then
91 later adopted as the preferred MRO (Method Resolution Order) for the
92 new-style classes in Python 2.3. Most recently it has been adopted as the
93 "canonical" MRO for Perl 6 classes, and the default MRO for Parrot objects
96 =head2 How does C3 work
98 C3 works by always preserving local precendence ordering. This essentially
99 means that no class will appear before any of its subclasses. Take, for
100 instance, the classic diamond inheritance pattern:
108 The standard Perl 5 MRO would be (D, B, A, C). The result being that B<A>
109 appears before B<C>, even though B<C> is the subclass of B<A>. The C3 MRO
110 algorithm however, produces the following order: (D, B, C, A), which does
113 This example is fairly trivial; for more complex cases and a deeper
114 explanation, see the links in the L</"SEE ALSO"> section.
118 =head2 mro::get_linear_isa($classname[, $type])
120 Returns an arrayref which is the linearized MRO of the given class.
121 Uses whichever MRO is currently in effect for that class by default,
122 or the given MRO (either C<c3> or C<dfs> if specified as C<$type>).
124 The linearized MRO of a class is an ordered array of all of the
125 classes one would search when resolving a method on that class,
126 starting with the class itself.
128 If the requested class doesn't yet exist, this function will still
129 succeed, and return C<[ $classname ]>
131 Note that C<UNIVERSAL> (and any members of C<UNIVERSAL>'s MRO) are not
132 part of the MRO of a class, even though all classes implicitly inherit
133 methods from C<UNIVERSAL> and its parents.
135 =head2 mro::set_mro($classname, $type)
137 Sets the MRO of the given class to the C<$type> argument (either
140 =head2 mro::get_mro($classname)
142 Returns the MRO of the given class (either C<c3> or C<dfs>).
144 =head2 mro::get_isarev($classname)
146 Gets the C<mro_isarev> for this class, returned as an
147 arrayref of class names. These are every class that "isa"
148 the given class name, even if the isa relationship is
149 indirect. This is used internally by the MRO code to
150 keep track of method/MRO cache invalidations.
152 Currently, this list only grows, it never shrinks. This
153 was a performance consideration (properly tracking and
154 deleting isarev entries when someone removes an entry
155 from an C<@ISA> is costly, and it doesn't happen often
156 anyways). The fact that a class which no longer truly
157 "isa" this class at runtime remains on the list should be
158 considered a quirky implementation detail which is subject
159 to future change. It shouldn't be an issue as long as
160 you're looking at this list for the same reasons the
161 core code does: as a performance optimization
162 over having to search every class in existence.
164 As with C<mro::get_mro> above, C<UNIVERSAL> is special.
165 C<UNIVERSAL> (and parents') isarev lists do not include
166 every class in existence, even though all classes are
167 effectively descendants for method inheritance purposes.
169 =head2 mro::is_universal($classname)
171 Returns a boolean status indicating whether or not
172 the given classname is either C<UNIVERSAL> itself,
173 or one of C<UNIVERSAL>'s parents by C<@ISA> inheritance.
175 Any class for which this function returns true is
176 "universal" in the sense that all classes potentially
177 inherit methods from it.
179 For similar reasons to C<isarev> above, this flag is
180 permanent. Once it is set, it does not go away, even
181 if the class in question really isn't universal anymore.
183 =head2 mro::invalidate_all_method_caches()
185 Increments C<PL_sub_generation>, which invalidates method
186 caching in all packages.
188 =head2 mro::method_changed_in($classname)
190 Invalidates the method cache of any classes dependent on the
191 given class. This is not normally necessary. The only
192 known case where pure perl code can confuse the method
193 cache is when you manually install a new constant
194 subroutine by using a readonly scalar value, like the
195 internals of L<constant> do. If you find another case,
196 please report it so we can either fix it or document
199 =head2 mro::get_pkg_gen($classname)
201 Returns an integer which is incremented every time a
202 real local method in the package C<$classname> changes,
203 or the local C<@ISA> of C<$classname> is modified.
205 This is intended for authors of modules which do lots
206 of class introspection, as it allows them to very quickly
207 check if anything important about the local properties
208 of a given class have changed since the last time they
209 looked. It does not increment on method/C<@ISA>
210 changes in superclasses.
212 It's still up to you to seek out the actual changes,
213 and there might not actually be any. Perhaps all
214 of the changes since you last checked cancelled each
215 other out and left the package in the state it was in
218 This integer normally starts off at a value of C<1>
219 when a package stash is instantiated. Calling it
220 on packages whose stashes do not exist at all will
221 return C<0>. If a package stash is completely
222 deleted (not a normal occurence, but it can happen
223 if someone does something like C<undef %PkgName::>),
224 the number will be reset to either C<0> or C<1>,
225 depending on how completely package was wiped out.
229 This is somewhat like C<SUPER>, but it uses the C3 method
230 resolution order to get better consistency in multiple
231 inheritance situations. Note that while inheritance in
232 general follows whichever MRO is in effect for the
233 given class, C<next::method> only uses the C3 MRO.
235 One generally uses it like so:
239 my $superclass_answer = $self->next::method(@_);
240 return $superclass_answer + 1;
243 Note that you don't (re-)specify the method name.
244 It forces you to always use the same method name
245 as the method you started in.
247 It can be called on an object or a class, of course.
249 The way it resolves which actual method to call is:
255 First, it determines the linearized C3 MRO of
256 the object or class it is being called on.
260 Then, it determines the class and method name
261 of the context it was invoked from.
265 Finally, it searches down the C3 MRO list until
266 it reaches the contextually enclosing class, then
267 searches further down the MRO list for the next
268 method with the same name as the contextually
273 Failure to find a next method will result in an
274 exception being thrown (see below for alternatives).
276 This is substantially different than the behavior
277 of C<SUPER> under complex multiple inheritance.
278 (This becomes obvious when one realizes that the
279 common superclasses in the C3 linearizations of
280 a given class and one of its parents will not
281 always be ordered the same for both.)
283 B<Caveat>: Calling C<next::method> from methods defined outside the class:
285 There is an edge case when using C<next::method> from within a subroutine
286 which was created in a different module than the one it is called from. It
287 sounds complicated, but it really isn't. Here is an example which will not
290 *Foo::foo = sub { (shift)->next::method(@_) };
292 The problem exists because the anonymous subroutine being assigned to the
293 C<*Foo::foo> glob will show up in the call stack as being called
294 C<__ANON__> and not C<foo> as you might expect. Since C<next::method> uses
295 C<caller> to find the name of the method it was called in, it will fail in
298 But fear not, there's a simple solution. The module C<Sub::Name> will
299 reach into the perl internals and assign a name to an anonymous subroutine
300 for you. Simply do this:
302 use Sub::Name 'subname';
303 *Foo::foo = subname 'Foo::foo' => sub { (shift)->next::method(@_) };
305 and things will Just Work.
309 This is similar to C<next::method>, but just returns either a code
310 reference or C<undef> to indicate that no further methods of this name
313 =head2 maybe::next::method
315 In simple cases, it is equivalent to:
317 $self->next::method(@_) if $self->next::can;
319 But there are some cases where only this solution
320 works (like C<goto &maybe::next::method>);
324 =head2 The original Dylan paper
328 =item L<http://www.webcom.com/haahr/dylan/linearization-oopsla96.html>
332 =head2 The prototype Perl 6 Object Model uses C3
336 =item L<http://svn.openfoundry.org/pugs/perl5/Perl6-MetaModel/>
340 =head2 Parrot now uses C3
344 =item L<http://aspn.activestate.com/ASPN/Mail/Message/perl6-internals/2746631>
346 =item L<http://use.perl.org/~autrijus/journal/25768>
350 =head2 Python 2.3 MRO related links
354 =item L<http://www.python.org/2.3/mro.html>
356 =item L<http://www.python.org/2.2.2/descrintro.html#mro>
360 =head2 C3 for TinyCLOS
364 =item L<http://www.call-with-current-continuation.org/eggs/c3.html>
378 Brandon L. Black, E<lt>blblack@gmail.comE<gt>
380 Based on Stevan Little's L<Class::C3>