Debian Codegraph @

upstream/opensuse-tumbleweed/man3/mro.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "mro 3pm"
61 .TH mro 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 mro \- Method Resolution Order
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use mro; # enables next::method and friends globally
72 \&
73 \& use mro \*(Aqdfs\*(Aq; # enable DFS MRO for this class (Perl default)
74 \& use mro \*(Aqc3\*(Aq; # enable C3 MRO for this class
75 .Ve
76 .SH DESCRIPTION
77 .IX Header "DESCRIPTION"
78 The "mro" namespace provides several utilities for dealing
79 with method resolution order and method caching in general.
80 .PP
81 These interfaces are only available in Perl 5.9.5 and higher.
82 See MRO::Compat on CPAN for a mostly forwards compatible
83 implementation for older Perls.
84 .SH OVERVIEW
85 .IX Header "OVERVIEW"
86 It\*(Aqs possible to change the MRO of a given class either by using \f(CW\*(C`use
87 mro\*(C'\fR as shown in the synopsis, or by using the "mro::set_mro" function
88 below.
89 .PP
90 The special methods \f(CW\*(C`next::method\*(C'\fR, \f(CW\*(C`next::can\*(C'\fR, and
91 \&\f(CW\*(C`maybe::next::method\*(C'\fR are not available until this \f(CW\*(C`mro\*(C'\fR module
92 has been loaded via \f(CW\*(C`use\*(C'\fR or \f(CW\*(C`require\*(C'\fR.
93 .SH "The C3 MRO"
94 .IX Header "The C3 MRO"
95 In addition to the traditional Perl default MRO (depth first
96 search, called \f(CW\*(C`DFS\*(C'\fR here), Perl now offers the C3 MRO as
97 well. Perl\*(Aqs support for C3 is based on the work done in
98 Stevan Little\*(Aqs module Class::C3, and most of the C3\-related
99 documentation here is ripped directly from there.
100 .SS "What is C3?"
101 .IX Subsection "What is C3?"
102 C3 is the name of an algorithm which aims to provide a sane method
103 resolution order under multiple inheritance. It was first introduced in
104 the language Dylan (see links in the "SEE ALSO" section), and then
105 later adopted as the preferred MRO (Method Resolution Order) for the
106 new\-style classes in Python 2.3. Most recently it has been adopted as the
107 "canonical" MRO for Raku classes.
108 .SS "How does C3 work"
109 .IX Subsection "How does C3 work"
110 C3 works by always preserving local precedence ordering. This essentially
111 means that no class will appear before any of its subclasses. Take, for
112 instance, the classic diamond inheritance pattern:
113 .PP
114 .Vb 5
115 \& <A>
116 \& / \e
117 \& <B> <C>
118 \& \e /
119 \& <D>
120 .Ve
121 .PP
122 The standard Perl 5 MRO would be (D, B, A, C). The result being that \fBA\fR
123 appears before \fBC\fR, even though \fBC\fR is the subclass of \fBA\fR. The C3 MRO
124 algorithm however, produces the following order: (D, B, C, A), which does
125 not have this issue.
126 .PP
127 This example is fairly trivial; for more complex cases and a deeper
128 explanation, see the links in the "SEE ALSO" section.
129 .SH Functions
130 .IX Header "Functions"
131 .ie n .SS "mro::get_linear_isa($classname[, $type])"
132 .el .SS "mro::get_linear_isa($classname[, \f(CW$type\fP])"
133 .IX Subsection "mro::get_linear_isa($classname[, $type])"
134 Returns an arrayref which is the linearized MRO of the given class.
135 Uses whichever MRO is currently in effect for that class by default,
136 or the given MRO (either \f(CW\*(C`c3\*(C'\fR or \f(CW\*(C`dfs\*(C'\fR if specified as \f(CW$type\fR).
137 .PP
138 The linearized MRO of a class is an ordered array of all of the
139 classes one would search when resolving a method on that class,
140 starting with the class itself.
141 .PP
142 If the requested class doesn\*(Aqt yet exist, this function will still
143 succeed, and return \f(CW\*(C`[ $classname ]\*(C'\fR
144 .PP
145 Note that \f(CW\*(C`UNIVERSAL\*(C'\fR (and any members of \f(CW\*(C`UNIVERSAL\*(C'\fR\*(Aqs MRO) are not
146 part of the MRO of a class, even though all classes implicitly inherit
147 methods from \f(CW\*(C`UNIVERSAL\*(C'\fR and its parents.
148 .ie n .SS "mro::set_mro ($classname, $type)"
149 .el .SS "mro::set_mro ($classname, \f(CW$type\fP)"
150 .IX Subsection "mro::set_mro ($classname, $type)"
151 Sets the MRO of the given class to the \f(CW$type\fR argument (either
152 \&\f(CW\*(C`c3\*(C'\fR or \f(CW\*(C`dfs\*(C'\fR).
153 .SS mro::get_mro($classname)
154 .IX Subsection "mro::get_mro($classname)"
155 Returns the MRO of the given class (either \f(CW\*(C`c3\*(C'\fR or \f(CW\*(C`dfs\*(C'\fR).
156 .SS mro::get_isarev($classname)
157 .IX Subsection "mro::get_isarev($classname)"
158 Gets the \f(CW\*(C`mro_isarev\*(C'\fR for this class, returned as an
159 arrayref of class names. These are every class that "isa"
160 the given class name, even if the isa relationship is
161 indirect. This is used internally by the MRO code to
162 keep track of method/MRO cache invalidations.
163 .PP
164 As with \f(CW\*(C`mro::get_linear_isa\*(C'\fR above, \f(CW\*(C`UNIVERSAL\*(C'\fR is special.
165 \&\f(CW\*(C`UNIVERSAL\*(C'\fR (and parents\*(Aq) isarev lists do not include
166 every class in existence, even though all classes are
167 effectively descendants for method inheritance purposes.
168 .SS mro::is_universal($classname)
169 .IX Subsection "mro::is_universal($classname)"
170 Returns a boolean status indicating whether or not
171 the given classname is either \f(CW\*(C`UNIVERSAL\*(C'\fR itself,
172 or one of \f(CW\*(C`UNIVERSAL\*(C'\fR\*(Aqs parents by \f(CW@ISA\fR inheritance.
173 .PP
174 Any class for which this function returns true is
175 "universal" in the sense that all classes potentially
176 inherit methods from it.
177 .SS \fBmro::invalidate_all_method_caches()\fP
178 .IX Subsection "mro::invalidate_all_method_caches()"
179 Increments \f(CW\*(C`PL_sub_generation\*(C'\fR, which invalidates method
180 caching in all packages.
181 .SS mro::method_changed_in($classname)
182 .IX Subsection "mro::method_changed_in($classname)"
183 Invalidates the method cache of any classes dependent on the
184 given class. This is not normally necessary. The only
185 known case where pure perl code can confuse the method
186 cache is when you manually install a new constant
187 subroutine by using a readonly scalar value, like the
188 internals of constant do. If you find another case,
189 please report it so we can either fix it or document
190 the exception here.
191 .SS mro::get_pkg_gen($classname)
192 .IX Subsection "mro::get_pkg_gen($classname)"
193 Returns an integer which is incremented every time a
194 real local method in the package \f(CW$classname\fR changes,
195 or the local \f(CW@ISA\fR of \f(CW$classname\fR is modified.
196 .PP
197 This is intended for authors of modules which do lots
198 of class introspection, as it allows them to very quickly
199 check if anything important about the local properties
200 of a given class have changed since the last time they
201 looked. It does not increment on method/\f(CW@ISA\fR
202 changes in superclasses.
203 .PP
204 It\*(Aqs still up to you to seek out the actual changes,
205 and there might not actually be any. Perhaps all
206 of the changes since you last checked cancelled each
207 other out and left the package in the state it was in
208 before.
209 .PP
210 This integer normally starts off at a value of \f(CW1\fR
211 when a package stash is instantiated. Calling it
212 on packages whose stashes do not exist at all will
213 return \f(CW0\fR. If a package stash is completely
214 deleted (not a normal occurrence, but it can happen
215 if someone does something like \f(CW\*(C`undef %PkgName::\*(C'\fR),
216 the number will be reset to either \f(CW0\fR or \f(CW1\fR,
217 depending on how completely the package was wiped out.
218 .SS next::method
219 .IX Subsection "next::method"
220 This is somewhat like \f(CW\*(C`SUPER\*(C'\fR, but it uses the C3 method
221 resolution order to get better consistency in multiple
222 inheritance situations. Note that while inheritance in
223 general follows whichever MRO is in effect for the
224 given class, \f(CW\*(C`next::method\*(C'\fR only uses the C3 MRO.
225 .PP
226 One generally uses it like so:
227 .PP
228 .Vb 5
229 \& sub some_method {
230 \& my $self = shift;
231 \& my $superclass_answer = $self\->next::method(@_);
232 \& return $superclass_answer + 1;
233 \& }
234 .Ve
235 .PP
236 Note that you don\*(Aqt (re\-)specify the method name.
237 It forces you to always use the same method name
238 as the method you started in.
239 .PP
240 It can be called on an object or a class, of course.
241 .PP
242 The way it resolves which actual method to call is:
243 .IP 1. 4
244 First, it determines the linearized C3 MRO of
245 the object or class it is being called on.
246 .IP 2. 4
247 Then, it determines the class and method name
248 of the context it was invoked from.
249 .IP 3. 4
250 Finally, it searches down the C3 MRO list until
251 it reaches the contextually enclosing class, then
252 searches further down the MRO list for the next
253 method with the same name as the contextually
254 enclosing method.
255 .PP
256 Failure to find a next method will result in an
257 exception being thrown (see below for alternatives).
258 .PP
259 This is substantially different than the behavior
260 of \f(CW\*(C`SUPER\*(C'\fR 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.)
265 .PP
266 \&\fBCaveat\fR: Calling \f(CW\*(C`next::method\*(C'\fR from methods defined outside the class:
267 .PP
268 There is an edge case when using \f(CW\*(C`next::method\*(C'\fR 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\*(Aqt. Here is an example which will not
271 work correctly:
272 .PP
273 .Vb 1
274 \& *Foo::foo = sub { (shift)\->next::method(@_) };
275 .Ve
276 .PP
277 The problem exists because the anonymous subroutine being assigned to the
278 \&\f(CW*Foo::foo\fR glob will show up in the call stack as being called
279 \&\f(CW\*(C`_\|_ANON_\|_\*(C'\fR and not \f(CW\*(C`foo\*(C'\fR as you might expect. Since \f(CW\*(C`next::method\*(C'\fR uses
280 \&\f(CW\*(C`caller\*(C'\fR to find the name of the method it was called in, it will fail in
281 this case.
282 .PP
283 But fear not, there\*(Aqs a simple solution. The module \f(CW\*(C`Sub::Name\*(C'\fR will
284 reach into the perl internals and assign a name to an anonymous subroutine
285 for you. Simply do this:
286 .PP
287 .Vb 2
288 \& use Sub::Name \*(Aqsubname\*(Aq;
289 \& *Foo::foo = subname \*(AqFoo::foo\*(Aq => sub { (shift)\->next::method(@_) };
290 .Ve
291 .PP
292 and things will Just Work.
293 .SS next::can
294 .IX Subsection "next::can"
295 This is similar to \f(CW\*(C`next::method\*(C'\fR, but just returns either a code
296 reference or \f(CW\*(C`undef\*(C'\fR to indicate that no further methods of this name
297 exist.
298 .SS maybe::next::method
299 .IX Subsection "maybe::next::method"
300 In simple cases, it is equivalent to:
301 .PP
302 .Vb 1
303 \& $self\->next::method(@_) if $self\->next::can;
304 .Ve
305 .PP
306 But there are some cases where only this solution
307 works (like \f(CW\*(C`goto &maybe::next::method\*(C'\fR);
308 .SH "SEE ALSO"
309 .IX Header "SEE ALSO"
310 .SS "The original Dylan paper"
311 .IX Subsection "The original Dylan paper"
312 .IP <http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.19.3910&rep=rep1&type=pdf> 4
313 .IX Item "<http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.19.3910&rep=rep1&type=pdf>"
314 .SS "Python 2.3 MRO"
315 .IX Subsection "Python 2.3 MRO"
316 .IP <https://www.python.org/download/releases/2.3/mro/> 4
317 .IX Item "<https://www.python.org/download/releases/2.3/mro/>"
318 .SS Class::C3
319 .IX Subsection "Class::C3"
320 .IP Class::C3 4
321 .IX Item "Class::C3"
322 .SH AUTHOR
323 .IX Header "AUTHOR"
324 Brandon L. Black, <[email protected]>
325 .PP
326 Based on Stevan Little\*(Aqs Class::C3