mro(3pm) - f14

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       Currently, this list only grows, it never shrinks.  This was a
98       performance consideration (properly tracking and deleting isarev
99       entries when someone removes an entry from an @ISA is costly, and it
100       doesn't happen often anyways).  The fact that a class which no longer
101       truly "isa" this class at runtime remains on the list should be
102       considered a quirky implementation detail which is subject to future
103       change.  It shouldn't be an issue as long as you're looking at this
104       list for the same reasons the core code does: as a performance
105       optimization over having to search every class in existence.
106
107       As with "mro::get_mro" above, "UNIVERSAL" is special.  "UNIVERSAL" (and
108       parents') isarev lists do not include every class in existence, even
109       though all classes are effectively descendants for method inheritance
110       purposes.
111
112   mro::is_universal($classname)
113       Returns a boolean status indicating whether or not the given classname
114       is either "UNIVERSAL" itself, or one of "UNIVERSAL"'s parents by @ISA
115       inheritance.
116
117       Any class for which this function returns true is "universal" in the
118       sense that all classes potentially inherit methods from it.
119
120       For similar reasons to "isarev" above, this flag is permanent.  Once it
121       is set, it does not go away, even if the class in question really isn't
122       universal anymore.
123
124   mro::invalidate_all_method_caches()
125       Increments "PL_sub_generation", which invalidates method caching in all
126       packages.
127
128   mro::method_changed_in($classname)
129       Invalidates the method cache of any classes dependent on the given
130       class.  This is not normally necessary.  The only known case where pure
131       perl code can confuse the method cache is when you manually install a
132       new constant subroutine by using a readonly scalar value, like the
133       internals of constant do.  If you find another case, please report it
134       so we can either fix it or document the exception here.
135
136   mro::get_pkg_gen($classname)
137       Returns an integer which is incremented every time a real local method
138       in the package $classname changes, or the local @ISA of $classname is
139       modified.
140
141       This is intended for authors of modules which do lots of class
142       introspection, as it allows them to very quickly check if anything
143       important about the local properties of a given class have changed
144       since the last time they looked.  It does not increment on method/@ISA
145       changes in superclasses.
146
147       It's still up to you to seek out the actual changes, and there might
148       not actually be any.  Perhaps all of the changes since you last checked
149       cancelled each other out and left the package in the state it was in
150       before.
151
152       This integer normally starts off at a value of 1 when a package stash
153       is instantiated.  Calling it on packages whose stashes do not exist at
154       all will return 0.  If a package stash is completely deleted (not a
155       normal occurence, but it can happen if someone does something like
156       "undef %PkgName::"), the number will be reset to either 0 or 1,
157       depending on how completely package was wiped out.
158
159   next::method
160       This is somewhat like "SUPER", but it uses the C3 method resolution
161       order to get better consistency in multiple inheritance situations.
162       Note that while inheritance in general follows whichever MRO is in
163       effect for the given class, "next::method" only uses the C3 MRO.
164
165       One generally uses it like so:
166
167         sub some_method {
168           my $self = shift;
169           my $superclass_answer = $self->next::method(@_);
170           return $superclass_answer + 1;
171         }
172
173       Note that you don't (re-)specify the method name.  It forces you to
174       always use the same method name as the method you started in.
175
176       It can be called on an object or a class, of course.
177
178       The way it resolves which actual method to call is:
179
180       1.  First, it determines the linearized C3 MRO of the object or class
181           it is being called on.
182
183       2.  Then, it determines the class and method name of the context it was
184           invoked from.
185
186       3.  Finally, it searches down the C3 MRO list until it reaches the
187           contextually enclosing class, then searches further down the MRO
188           list for the next method with the same name as the contextually
189           enclosing method.
190
191       Failure to find a next method will result in an exception being thrown
192       (see below for alternatives).
193
194       This is substantially different than the behavior of "SUPER" under
195       complex multiple inheritance.  (This becomes obvious when one realizes
196       that the common superclasses in the C3 linearizations of a given class
197       and one of its parents will not always be ordered the same for both.)
198
199       Caveat: Calling "next::method" from methods defined outside the class:
200
201       There is an edge case when using "next::method" from within a
202       subroutine which was created in a different module than the one it is
203       called from. It sounds complicated, but it really isn't. Here is an
204       example which will not work correctly:
205
206         *Foo::foo = sub { (shift)->next::method(@_) };
207
208       The problem exists because the anonymous subroutine being assigned to
209       the *Foo::foo glob will show up in the call stack as being called
210       "__ANON__" and not "foo" as you might expect. Since "next::method" uses
211       "caller" to find the name of the method it was called in, it will fail
212       in this case.
213
214       But fear not, there's a simple solution. The module "Sub::Name" will
215       reach into the perl internals and assign a name to an anonymous
216       subroutine for you. Simply do this:
217
218         use Sub::Name 'subname';
219         *Foo::foo = subname 'Foo::foo' => sub { (shift)->next::method(@_) };
220
221       and things will Just Work.
222
223   next::can
224       This is similar to "next::method", but just returns either a code
225       reference or "undef" to indicate that no further methods of this name
226       exist.
227
228   maybe::next::method
229       In simple cases, it is equivalent to:
230
231          $self->next::method(@_) if $self->next::can;
232
233       But there are some cases where only this solution works (like "goto
234       &maybe::next::method");
235

AUTHOR

263       Brandon L. Black, <blblack@gmail.com>
264
265       Based on Stevan Little's Class::C3
266
267
268
269perl v5.12.4                      2011-06-07                          mro(3pm)