Debian Codegraph @

upstream/debian-unstable/man3/mro.3perl

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