3 # Copyright (c) 2007 Brandon L Black
4 # Copyright (c) 2008,2009 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.09';
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');
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
73 The special methods C<next::method>, C<next::can>, and
74 C<maybe::next::method> are not available until this C<mro> module
75 has been loaded via C<use> or C<require>.
79 In addition to the traditional Perl default MRO (depth first
80 search, called C<DFS> here), Perl now offers the C3 MRO as
81 well. Perl's support for C3 is based on the work done in
82 Stevan Little's module L<Class::C3>, and most of the C3-related
83 documentation here is ripped directly from there.
87 C3 is the name of an algorithm which aims to provide a sane method
88 resolution order under multiple inheritance. It was first introduced in
89 the language Dylan (see links in the L</"SEE ALSO"> section), and then
90 later adopted as the preferred MRO (Method Resolution Order) for the
91 new-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
95 =head2 How does C3 work
97 C3 works by always preserving local precedence ordering. This essentially
98 means that no class will appear before any of its subclasses. Take, for
99 instance, the classic diamond inheritance pattern:
107 The standard Perl 5 MRO would be (D, B, A, C). The result being that B<A>
108 appears before B<C>, even though B<C> is the subclass of B<A>. The C3 MRO
109 algorithm however, produces the following order: (D, B, C, A), which does
112 This example is fairly trivial; for more complex cases and a deeper
113 explanation, see the links in the L</"SEE ALSO"> section.
117 =head2 mro::get_linear_isa($classname[, $type])
119 Returns an arrayref which is the linearized MRO of the given class.
120 Uses whichever MRO is currently in effect for that class by default,
121 or the given MRO (either C<c3> or C<dfs> if specified as C<$type>).
123 The linearized MRO of a class is an ordered array of all of the
124 classes one would search when resolving a method on that class,
125 starting with the class itself.
127 If the requested class doesn't yet exist, this function will still
128 succeed, and return C<[ $classname ]>
130 Note that C<UNIVERSAL> (and any members of C<UNIVERSAL>'s MRO) are not
131 part of the MRO of a class, even though all classes implicitly inherit
132 methods from C<UNIVERSAL> and its parents.
134 =head2 mro::set_mro ($classname, $type)
136 Sets the MRO of the given class to the C<$type> argument (either
139 =head2 mro::get_mro($classname)
141 Returns the MRO of the given class (either C<c3> or C<dfs>).
143 =head2 mro::get_isarev($classname)
145 Gets the C<mro_isarev> for this class, returned as an
146 arrayref of class names. These are every class that "isa"
147 the given class name, even if the isa relationship is
148 indirect. This is used internally by the MRO code to
149 keep track of method/MRO cache invalidations.
151 As with C<mro::get_linear_isa> above, C<UNIVERSAL> is special.
152 C<UNIVERSAL> (and parents') isarev lists do not include
153 every class in existence, even though all classes are
154 effectively descendants for method inheritance purposes.
156 =head2 mro::is_universal($classname)
158 Returns a boolean status indicating whether or not
159 the given classname is either C<UNIVERSAL> itself,
160 or one of C<UNIVERSAL>'s parents by C<@ISA> inheritance.
162 Any class for which this function returns true is
163 "universal" in the sense that all classes potentially
164 inherit methods from it.
166 =head2 mro::invalidate_all_method_caches()
168 Increments C<PL_sub_generation>, which invalidates method
169 caching in all packages.
171 =head2 mro::method_changed_in($classname)
173 Invalidates the method cache of any classes dependent on the
174 given class. This is not normally necessary. The only
175 known case where pure perl code can confuse the method
176 cache is when you manually install a new constant
177 subroutine by using a readonly scalar value, like the
178 internals of L<constant> do. If you find another case,
179 please report it so we can either fix it or document
182 =head2 mro::get_pkg_gen($classname)
184 Returns an integer which is incremented every time a
185 real local method in the package C<$classname> changes,
186 or the local C<@ISA> of C<$classname> is modified.
188 This is intended for authors of modules which do lots
189 of class introspection, as it allows them to very quickly
190 check if anything important about the local properties
191 of a given class have changed since the last time they
192 looked. It does not increment on method/C<@ISA>
193 changes in superclasses.
195 It's still up to you to seek out the actual changes,
196 and there might not actually be any. Perhaps all
197 of the changes since you last checked cancelled each
198 other out and left the package in the state it was in
201 This integer normally starts off at a value of C<1>
202 when a package stash is instantiated. Calling it
203 on packages whose stashes do not exist at all will
204 return C<0>. If a package stash is completely
205 deleted (not a normal occurence, but it can happen
206 if someone does something like C<undef %PkgName::>),
207 the number will be reset to either C<0> or C<1>,
208 depending on how completely package was wiped out.
212 This is somewhat like C<SUPER>, but it uses the C3 method
213 resolution order to get better consistency in multiple
214 inheritance situations. Note that while inheritance in
215 general follows whichever MRO is in effect for the
216 given class, C<next::method> only uses the C3 MRO.
218 One generally uses it like so:
222 my $superclass_answer = $self->next::method(@_);
223 return $superclass_answer + 1;
226 Note that you don't (re-)specify the method name.
227 It forces you to always use the same method name
228 as the method you started in.
230 It can be called on an object or a class, of course.
232 The way it resolves which actual method to call is:
238 First, it determines the linearized C3 MRO of
239 the object or class it is being called on.
243 Then, it determines the class and method name
244 of the context it was invoked from.
248 Finally, it searches down the C3 MRO list until
249 it reaches the contextually enclosing class, then
250 searches further down the MRO list for the next
251 method with the same name as the contextually
256 Failure to find a next method will result in an
257 exception being thrown (see below for alternatives).
259 This is substantially different than the behavior
260 of C<SUPER> under complex multiple inheritance.
261 (This becomes obvious when one realizes that the
262 common superclasses in the C3 linearizations of
263 a given class and one of its parents will not
264 always be ordered the same for both.)
266 B<Caveat>: Calling C<next::method> from methods defined outside the class:
268 There is an edge case when using C<next::method> from within a subroutine
269 which was created in a different module than the one it is called from. It
270 sounds complicated, but it really isn't. Here is an example which will not
273 *Foo::foo = sub { (shift)->next::method(@_) };
275 The problem exists because the anonymous subroutine being assigned to the
276 C<*Foo::foo> glob will show up in the call stack as being called
277 C<__ANON__> and not C<foo> as you might expect. Since C<next::method> uses
278 C<caller> to find the name of the method it was called in, it will fail in
281 But fear not, there's a simple solution. The module C<Sub::Name> will
282 reach into the perl internals and assign a name to an anonymous subroutine
283 for you. Simply do this:
285 use Sub::Name 'subname';
286 *Foo::foo = subname 'Foo::foo' => sub { (shift)->next::method(@_) };
288 and things will Just Work.
292 This is similar to C<next::method>, but just returns either a code
293 reference or C<undef> to indicate that no further methods of this name
296 =head2 maybe::next::method
298 In simple cases, it is equivalent to:
300 $self->next::method(@_) if $self->next::can;
302 But there are some cases where only this solution
303 works (like C<goto &maybe::next::method>);
307 =head2 The original Dylan paper
311 =item L<http://www.webcom.com/haahr/dylan/linearization-oopsla96.html>
317 The Pugs prototype Perl 6 Object Model uses C3
325 =item L<http://use.perl.org/~autrijus/journal/25768>
329 =head2 Python 2.3 MRO related links
333 =item L<http://www.python.org/2.3/mro.html>
335 =item L<http://www.python.org/2.2.2/descrintro.html#mro>
349 Brandon L. Black, E<lt>blblack@gmail.comE<gt>
351 Based on Stevan Little's L<Class::C3>