mro(3pm)

1mro(3pm)               Perl Programmers Reference Guide               mro(3pm)
2
3
4

NAME

6       mro - Method Resolution Order
7

SYNOPSIS

9         use mro; # enables next::method and friends globally
10
11         use mro 'dfs'; # enable DFS MRO for this class (Perl default)
12         use mro 'c3'; # enable C3 MRO for this class
13

DESCRIPTION

15       The "mro" namespace provides several utilities for dealing with method
16       resolution order and method caching in general.
17
18       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

OVERVIEW

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
27       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

The C3 MRO

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
38   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 Perl 6 classes, and the default MRO for Parrot
45       objects as well.
46
47   How does C3 work
48       C3 works by always preserving local precedence ordering. This
49       essentially means that no class will appear before any of its
50       subclasses. Take, for instance, the classic diamond inheritance
51       pattern:
52
53            <A>
54           /   \
55         <B>   <C>
56           \   /
57            <D>
58
59       The standard Perl 5 MRO would be (D, B, A, C). The result being that A
60       appears before C, even though C is the subclass of A. The C3 MRO
61       algorithm however, produces the following order: (D, B, C, A), which
62       does not have this issue.
63
64       This example is fairly trivial; for more complex cases and a deeper
65       explanation, see the links in the "SEE ALSO" section.
66

Functions

68   mro::get_linear_isa($classname[, $type])
69       Returns an arrayref which is the linearized MRO of the given class.
70       Uses whichever MRO is currently in effect for that class by default, or
71       the given MRO (either "c3" or "dfs" if specified as $type).
72
73       The linearized MRO of a class is an ordered array of all of the classes
74       one would search when resolving a method on that class, starting with
75       the class itself.
76
77       If the requested class doesn't yet exist, this function will still
78       succeed, and return "[ $classname ]"
79
80       Note that "UNIVERSAL" (and any members of "UNIVERSAL"'s MRO) are not
81       part of the MRO of a class, even though all classes implicitly inherit
82       methods from "UNIVERSAL" and its parents.
83
84   mro::set_mro ($classname, $type)
85       Sets the MRO of the given class to the $type argument (either "c3" or
86       "dfs").
87
88   mro::get_mro($classname)
89       Returns the MRO of the given class (either "c3" or "dfs").
90
91   mro::get_isarev($classname)
92       Gets the "mro_isarev" for this class, returned as an arrayref of class
93       names.  These are every class that "isa" the given class name, even if
94       the isa relationship is indirect.  This is used internally by the MRO
95       code to keep track of method/MRO cache invalidations.
96
97       As with "mro::get_linear_isa" above, "UNIVERSAL" is special.
98       "UNIVERSAL" (and parents') isarev lists do not include every class in
99       existence, even though all classes are effectively descendants for
100       method inheritance purposes.
101
102   mro::is_universal($classname)
103       Returns a boolean status indicating whether or not the given classname
104       is either "UNIVERSAL" itself, or one of "UNIVERSAL"'s parents by @ISA
105       inheritance.
106
107       Any class for which this function returns true is "universal" in the
108       sense that all classes potentially inherit methods from it.
109
110   mro::invalidate_all_method_caches()
111       Increments "PL_sub_generation", which invalidates method caching in all
112       packages.
113
114   mro::method_changed_in($classname)
115       Invalidates the method cache of any classes dependent on the given
116       class.  This is not normally necessary.  The only known case where pure
117       perl code can confuse the method cache is when you manually install a
118       new constant subroutine by using a readonly scalar value, like the
119       internals of constant do.  If you find another case, please report it
120       so we can either fix it or document the exception here.
121
122   mro::get_pkg_gen($classname)
123       Returns an integer which is incremented every time a real local method
124       in the package $classname changes, or the local @ISA of $classname is
125       modified.
126
127       This is intended for authors of modules which do lots of class
128       introspection, as it allows them to very quickly check if anything
129       important about the local properties of a given class have changed
130       since the last time they looked.  It does not increment on method/@ISA
131       changes in superclasses.
132
133       It's still up to you to seek out the actual changes, and there might
134       not actually be any.  Perhaps all of the changes since you last checked
135       cancelled each other out and left the package in the state it was in
136       before.
137
138       This integer normally starts off at a value of 1 when a package stash
139       is instantiated.  Calling it on packages whose stashes do not exist at
140       all will return 0.  If a package stash is completely deleted (not a
141       normal occurrence, but it can happen if someone does something like
142       "undef %PkgName::"), the number will be reset to either 0 or 1,
143       depending on how completely the package was wiped out.
144
145   next::method
146       This is somewhat like "SUPER", but it uses the C3 method resolution
147       order to get better consistency in multiple inheritance situations.
148       Note that while inheritance in general follows whichever MRO is in
149       effect for the given class, "next::method" only uses the C3 MRO.
150
151       One generally uses it like so:
152
153         sub some_method {
154           my $self = shift;
155           my $superclass_answer = $self->next::method(@_);
156           return $superclass_answer + 1;
157         }
158
159       Note that you don't (re-)specify the method name.  It forces you to
160       always use the same method name as the method you started in.
161
162       It can be called on an object or a class, of course.
163
164       The way it resolves which actual method to call is:
165
166       1.  First, it determines the linearized C3 MRO of the object or class
167           it is being called on.
168
169       2.  Then, it determines the class and method name of the context it was
170           invoked from.
171
172       3.  Finally, it searches down the C3 MRO list until it reaches the
173           contextually enclosing class, then searches further down the MRO
174           list for the next method with the same name as the contextually
175           enclosing method.
176
177       Failure to find a next method will result in an exception being thrown
178       (see below for alternatives).
179
180       This is substantially different than the behavior of "SUPER" under
181       complex multiple inheritance.  (This becomes obvious when one realizes
182       that the common superclasses in the C3 linearizations of a given class
183       and one of its parents will not always be ordered the same for both.)
184
185       Caveat: Calling "next::method" from methods defined outside the class:
186
187       There is an edge case when using "next::method" from within a
188       subroutine which was created in a different module than the one it is
189       called from. It sounds complicated, but it really isn't. Here is an
190       example which will not work correctly:
191
192         *Foo::foo = sub { (shift)->next::method(@_) };
193
194       The problem exists because the anonymous subroutine being assigned to
195       the *Foo::foo glob will show up in the call stack as being called
196       "__ANON__" and not "foo" as you might expect. Since "next::method" uses
197       "caller" to find the name of the method it was called in, it will fail
198       in this case.
199
200       But fear not, there's a simple solution. The module "Sub::Name" will
201       reach into the perl internals and assign a name to an anonymous
202       subroutine for you. Simply do this:
203
204         use Sub::Name 'subname';
205         *Foo::foo = subname 'Foo::foo' => sub { (shift)->next::method(@_) };
206
207       and things will Just Work.
208
209   next::can
210       This is similar to "next::method", but just returns either a code
211       reference or "undef" to indicate that no further methods of this name
212       exist.
213
214   maybe::next::method
215       In simple cases, it is equivalent to:
216
217          $self->next::method(@_) if $self->next::can;
218
219       But there are some cases where only this solution works (like "goto
220       &maybe::next::method");
221

AUTHOR

242       Brandon L. Black, <blblack@gmail.com>
243
244       Based on Stevan Little's Class::C3
245
246
247
248perl v5.26.3                      2018-03-23                          mro(3pm)