1mro(3pm) Perl Programmers Reference Guide mro(3pm)
2
6 mro - Method Resolution Order
7
9 use mro; # enables next::method and friends globally
10 use mro 'dfs'; # enable DFS MRO for this class (Perl default)
12 use mro 'c3'; # enable C3 MRO for this class
13
15 The "mro" namespace provides several utilities for dealing with method
16 resolution order and method caching in general.
17 These interfaces are only available in Perl 5.9.5 and higher. See
19 MRO::Compat on CPAN for a mostly forwards compatible implementation for
20 older Perls.
21
23 It's possible to change the MRO of a given class either by using "use
24 mro" as shown in the synopsis, or by using the "mro::set_mro" function
25 below.
26 The special methods "next::method", "next::can", and
28 "maybe::next::method" are not available until this "mro" module has
29 been loaded via "use" or "require".
30
32 In addition to the traditional Perl default MRO (depth first search,
33 called "DFS" here), Perl now offers the C3 MRO as well. Perl's support
34 for C3 is based on the work done in Stevan Little's module Class::C3,
35 and most of the C3-related documentation here is ripped directly from
36 there.
37 What is C3?
39 C3 is the name of an algorithm which aims to provide a sane method
40 resolution order under multiple inheritance. It was first introduced in
41 the language Dylan (see links in the "SEE ALSO" section), and then
42 later adopted as the preferred MRO (Method Resolution Order) for the
43 new-style classes in Python 2.3. Most recently it has been adopted as
44 the "canonical" MRO for Raku classes.
45 How does C3 work
47 C3 works by always preserving local precedence ordering. This
48 essentially means that no class will appear before any of its
49 subclasses. Take, for instance, the classic diamond inheritance
50 pattern:
51 <A>
53 / \
54 <B> <C>
55 \ /
56 <D>
57 The standard Perl 5 MRO would be (D, B, A, C). The result being that A
59 appears before C, even though C is the subclass of A. The C3 MRO
60 algorithm however, produces the following order: (D, B, C, A), which
61 does not have this issue.
62 This example is fairly trivial; for more complex cases and a deeper
64 explanation, see the links in the "SEE ALSO" section.
65
67 mro::get_linear_isa($classname[, $type])
68 Returns an arrayref which is the linearized MRO of the given class.
69 Uses whichever MRO is currently in effect for that class by default, or
70 the given MRO (either "c3" or "dfs" if specified as $type).
71 The linearized MRO of a class is an ordered array of all of the classes
73 one would search when resolving a method on that class, starting with
74 the class itself.
75 If the requested class doesn't yet exist, this function will still
77 succeed, and return "[ $classname ]"
78 Note that "UNIVERSAL" (and any members of "UNIVERSAL"'s MRO) are not
80 part of the MRO of a class, even though all classes implicitly inherit
81 methods from "UNIVERSAL" and its parents.
82 mro::set_mro ($classname, $type)
84 Sets the MRO of the given class to the $type argument (either "c3" or
85 "dfs").
86 mro::get_mro($classname)
88 Returns the MRO of the given class (either "c3" or "dfs").
89 mro::get_isarev($classname)
91 Gets the "mro_isarev" for this class, returned as an arrayref of class
92 names. These are every class that "isa" the given class name, even if
93 the isa relationship is indirect. This is used internally by the MRO
94 code to keep track of method/MRO cache invalidations.
95 As with "mro::get_linear_isa" above, "UNIVERSAL" is special.
97 "UNIVERSAL" (and parents') isarev lists do not include every class in
98 existence, even though all classes are effectively descendants for
99 method inheritance purposes.
100 mro::is_universal($classname)
102 Returns a boolean status indicating whether or not the given classname
103 is either "UNIVERSAL" itself, or one of "UNIVERSAL"'s parents by @ISA
104 inheritance.
105 Any class for which this function returns true is "universal" in the
107 sense that all classes potentially inherit methods from it.
108 mro::invalidate_all_method_caches()
110 Increments "PL_sub_generation", which invalidates method caching in all
111 packages.
112 mro::method_changed_in($classname)
114 Invalidates the method cache of any classes dependent on the given
115 class. This is not normally necessary. The only known case where pure
116 perl code can confuse the method cache is when you manually install a
117 new constant subroutine by using a readonly scalar value, like the
118 internals of constant do. If you find another case, please report it
119 so we can either fix it or document the exception here.
120 mro::get_pkg_gen($classname)
122 Returns an integer which is incremented every time a real local method
123 in the package $classname changes, or the local @ISA of $classname is
124 modified.
125 This is intended for authors of modules which do lots of class
127 introspection, as it allows them to very quickly check if anything
128 important about the local properties of a given class have changed
129 since the last time they looked. It does not increment on method/@ISA
130 changes in superclasses.
131 It's still up to you to seek out the actual changes, and there might
133 not actually be any. Perhaps all of the changes since you last checked
134 cancelled each other out and left the package in the state it was in
135 before.
136 This integer normally starts off at a value of 1 when a package stash
138 is instantiated. Calling it on packages whose stashes do not exist at
139 all will return 0. If a package stash is completely deleted (not a
140 normal occurrence, but it can happen if someone does something like
141 "undef %PkgName::"), the number will be reset to either 0 or 1,
142 depending on how completely the package was wiped out.
143 next::method
145 This is somewhat like "SUPER", but it uses the C3 method resolution
146 order to get better consistency in multiple inheritance situations.
147 Note that while inheritance in general follows whichever MRO is in
148 effect for the given class, "next::method" only uses the C3 MRO.
149 One generally uses it like so:
151 sub some_method {
153 my $self = shift;
154 my $superclass_answer = $self->next::method(@_);
155 return $superclass_answer + 1;
156 }
157 Note that you don't (re-)specify the method name. It forces you to
159 always use the same method name as the method you started in.
160 It can be called on an object or a class, of course.
162 The way it resolves which actual method to call is:
164 1. First, it determines the linearized C3 MRO of the object or class
166 it is being called on.
167 2. Then, it determines the class and method name of the context it was
169 invoked from.
170 3. Finally, it searches down the C3 MRO list until it reaches the
172 contextually enclosing class, then searches further down the MRO
173 list for the next method with the same name as the contextually
174 enclosing method.
175 Failure to find a next method will result in an exception being thrown
177 (see below for alternatives).
178 This is substantially different than the behavior of "SUPER" under
180 complex multiple inheritance. (This becomes obvious when one realizes
181 that the common superclasses in the C3 linearizations of a given class
182 and one of its parents will not always be ordered the same for both.)
183 Caveat: Calling "next::method" from methods defined outside the class:
185 There is an edge case when using "next::method" from within a
187 subroutine which was created in a different module than the one it is
188 called from. It sounds complicated, but it really isn't. Here is an
189 example which will not work correctly:
190 *Foo::foo = sub { (shift)->next::method(@_) };
192 The problem exists because the anonymous subroutine being assigned to
194 the *Foo::foo glob will show up in the call stack as being called
195 "__ANON__" and not "foo" as you might expect. Since "next::method" uses
196 "caller" to find the name of the method it was called in, it will fail
197 in this case.
198 But fear not, there's a simple solution. The module "Sub::Name" will
200 reach into the perl internals and assign a name to an anonymous
201 subroutine for you. Simply do this:
202 use Sub::Name 'subname';
204 *Foo::foo = subname 'Foo::foo' => sub { (shift)->next::method(@_) };
205 and things will Just Work.
207 next::can
209 This is similar to "next::method", but just returns either a code
210 reference or "undef" to indicate that no further methods of this name
211 exist.
212 maybe::next::method
214 In simple cases, it is equivalent to:
215 $self->next::method(@_) if $self->next::can;
217 But there are some cases where only this solution works (like "goto
219 &maybe::next::method");
220
222 The original Dylan paper
223 <http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.19.3910&rep=rep1&type=pdf>
224 Python 2.3 MRO
226 <https://www.python.org/download/releases/2.3/mro/>
227 Class::C3
229 Class::C3
230
232 Brandon L. Black, <blblack@gmail.com>
233 Based on Stevan Little's Class::C3
235perl v5.36.3 2023-11-30 mro(3pm)