This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
threads 1.62
[perl5.git] / lib / mro.pm
CommitLineData
e1a479c5
BB
1# mro.pm
2#
3# Copyright (c) 2007 Brandon L Black
4#
5# You may distribute under the terms of either the GNU General Public
6# License or the Artistic License, as specified in the README file.
7#
8package mro;
9use strict;
10use warnings;
11
12# mro.pm versions < 1.00 reserved for possible CPAN mro dist
13# (for partial back-compat to 5.[68].x)
14our $VERSION = '1.00';
15
16sub import {
17 mro::set_mro(scalar(caller), $_[1]) if $_[1];
18}
19
201;
21
22__END__
23
24=head1 NAME
25
26mro - Method Resolution Order
27
28=head1 SYNOPSIS
29
2e4b0c4a
RGS
30 use mro 'dfs'; # enable DFS MRO for this class (Perl default)
31 use mro 'c3'; # enable C3 MRO for this class
e1a479c5
BB
32
33=head1 DESCRIPTION
34
35The "mro" namespace provides several utilities for dealing
36with method resolution order and method caching in general.
37
38=head1 OVERVIEW
39
2e4b0c4a
RGS
40It's possible to change the MRO of a given class either by using C<use
41mro> as shown in the synopsis, or by using the L</mro::set_mro> function
42below. The functions do not require loading the C<mro> module, as they
43are actually provided by the core perl interpreter. The C<use mro> syntax
44is just syntactic sugar for setting the current package's MRO.
e1a479c5
BB
45
46=head1 The C3 MRO
47
48In addition to the traditional Perl default MRO (depth first
2e4b0c4a 49search, called C<DFS> here), Perl now offers the C3 MRO as
e1a479c5 50well. Perl's support for C3 is based on the work done in
2e4b0c4a 51Stevan Little's module L<Class::C3>, and most of the C3-related
e1a479c5
BB
52documentation here is ripped directly from there.
53
54=head2 What is C3?
55
2e4b0c4a
RGS
56C3 is the name of an algorithm which aims to provide a sane method
57resolution order under multiple inheritance. It was first introduced in
58the language Dylan (see links in the L</"SEE ALSO"> section), and then
59later adopted as the preferred MRO (Method Resolution Order) for the
60new-style classes in Python 2.3. Most recently it has been adopted as the
61"canonical" MRO for Perl 6 classes, and the default MRO for Parrot objects
62as well.
e1a479c5 63
2e4b0c4a 64=head2 How does C3 work
e1a479c5 65
2e4b0c4a
RGS
66C3 works by always preserving local precendence ordering. This essentially
67means that no class will appear before any of its subclasses. Take, for
68instance, the classic diamond inheritance pattern:
e1a479c5
BB
69
70 <A>
71 / \
72 <B> <C>
73 \ /
74 <D>
75
2e4b0c4a
RGS
76The standard Perl 5 MRO would be (D, B, A, C). The result being that B<A>
77appears before B<C>, even though B<C> is the subclass of B<A>. The C3 MRO
78algorithm however, produces the following order: (D, B, C, A), which does
79not have this issue.
e1a479c5 80
2e4b0c4a
RGS
81This example is fairly trivial; for more complex cases and a deeper
82explanation, see the links in the L</"SEE ALSO"> section.
e1a479c5
BB
83
84=head1 Functions
85
2e4b0c4a 86=head2 mro::get_linear_isa($classname[, $type])
e1a479c5 87
2e4b0c4a 88Returns an arrayref which is the linearized MRO of the given class.
e1a479c5 89Uses whichever MRO is currently in effect for that class by default,
2e4b0c4a 90or the given MRO (either C<c3> or C<dfs> if specified as C<$type>).
e1a479c5 91
2e4b0c4a
RGS
92Note that C<UNIVERSAL> (and any members of C<UNIVERSAL>'s MRO) are not
93part of the MRO of a class, even though all classes implicitly inherit
e1a479c5
BB
94methods from C<UNIVERSAL> and its parents.
95
2e4b0c4a 96=head2 mro::set_mro($classname, $type)
e1a479c5 97
2e4b0c4a 98Sets the MRO of the given class to the C<$type> argument (either
e1a479c5
BB
99C<c3> or C<dfs>).
100
2e4b0c4a 101=head2 mro::get_mro($classname)
e1a479c5 102
2e4b0c4a 103Returns the MRO of the given class (either C<c3> or C<dfs>).
e1a479c5 104
2e4b0c4a 105=head2 mro::get_isarev($classname)
e1a479c5
BB
106
107Gets the C<mro_isarev> for this class, returned as an
2e4b0c4a
RGS
108array of class names. These are every class that "isa"
109the given class name, even if the isa relationship is
110indirect. This is used internally by the MRO code to
111keep track of method/MRO cache invalidations.
e1a479c5
BB
112
113Currently, this list only grows, it never shrinks. This
114was a performance consideration (properly tracking and
115deleting isarev entries when someone removes an entry
116from an C<@ISA> is costly, and it doesn't happen often
117anyways). The fact that a class which no longer truly
118"isa" this class at runtime remains on the list should be
119considered a quirky implementation detail which is subject
120to future change. It shouldn't be an issue as long as
121you're looking at this list for the same reasons the
122core code does: as a performance optimization
123over having to search every class in existence.
124
125As with C<mro::get_mro> above, C<UNIVERSAL> is special.
126C<UNIVERSAL> (and parents') isarev lists do not include
127every class in existence, even though all classes are
128effectively descendants for method inheritance purposes.
129
2e4b0c4a 130=head2 mro::is_universal($classname)
e1a479c5
BB
131
132Returns a boolean status indicating whether or not
133the given classname is either C<UNIVERSAL> itself,
134or one of C<UNIVERSAL>'s parents by C<@ISA> inheritance.
135
136Any class for which this function returns true is
137"universal" in the sense that all classes potentially
138inherit methods from it.
139
140For similar reasons to C<isarev> above, this flag is
141permanent. Once it is set, it does not go away, even
142if the class in question really isn't universal anymore.
143
2e4b0c4a 144=head2 mro::invalidate_all_method_caches()
e1a479c5
BB
145
146Increments C<PL_sub_generation>, which invalidates method
147caching in all packages.
148
2e4b0c4a 149=head2 mro::method_changed_in($classname)
e1a479c5 150
2e4b0c4a 151Invalidates the method cache of any classes dependent on the
e1a479c5
BB
152given class.
153
154=head2 next::method
155
156This is somewhat like C<SUPER>, but it uses the C3 method
157resolution order to get better consistency in multiple
158inheritance situations. Note that while inheritance in
159general follows whichever MRO is in effect for the
160given class, C<next::method> only uses the C3 MRO.
161
162One generally uses it like so:
163
164 sub some_method {
165 my $self = shift;
e1a479c5
BB
166 my $superclass_answer = $self->next::method(@_);
167 return $superclass_answer + 1;
168 }
169
170Note that you don't (re-)specify the method name.
171It forces you to always use the same method name
172as the method you started in.
173
174It can be called on an object or a class, of course.
175
176The way it resolves which actual method to call is:
177
2e4b0c4a
RGS
178=over 4
179
180=item 1
181
182First, it determines the linearized C3 MRO of
e1a479c5
BB
183the object or class it is being called on.
184
2e4b0c4a
RGS
185=item 2
186
187Then, it determines the class and method name
e1a479c5
BB
188of the context it was invoked from.
189
2e4b0c4a
RGS
190=item 3
191
192Finally, it searches down the C3 MRO list until
e1a479c5
BB
193it reaches the contextually enclosing class, then
194searches further down the MRO list for the next
195method with the same name as the contextually
196enclosing method.
197
2e4b0c4a
RGS
198=back
199
e1a479c5
BB
200Failure to find a next method will result in an
201exception being thrown (see below for alternatives).
202
203This is substantially different than the behavior
2e4b0c4a
RGS
204of C<SUPER> under complex multiple inheritance.
205(This becomes obvious when one realizes that the
e1a479c5
BB
206common superclasses in the C3 linearizations of
207a given class and one of its parents will not
2e4b0c4a 208always be ordered the same for both.)
e1a479c5 209
2e4b0c4a 210B<Caveat>: Calling C<next::method> from methods defined outside the class:
e1a479c5 211
2e4b0c4a
RGS
212There is an edge case when using C<next::method> from within a subroutine
213which was created in a different module than the one it is called from. It
214sounds complicated, but it really isn't. Here is an example which will not
215work correctly:
e1a479c5
BB
216
217 *Foo::foo = sub { (shift)->next::method(@_) };
218
2e4b0c4a
RGS
219The problem exists because the anonymous subroutine being assigned to the
220C<*Foo::foo> glob will show up in the call stack as being called
221C<__ANON__> and not C<foo> as you might expect. Since C<next::method> uses
222C<caller> to find the name of the method it was called in, it will fail in
223this case.
224
225But fear not, there's a simple solution. The module C<Sub::Name> will
226reach into the perl internals and assign a name to an anonymous subroutine
227for you. Simply do this:
e1a479c5 228
e1a479c5
BB
229 use Sub::Name 'subname';
230 *Foo::foo = subname 'Foo::foo' => sub { (shift)->next::method(@_) };
231
232and things will Just Work.
233
234=head2 next::can
235
2e4b0c4a
RGS
236This is similar to C<next::method>, but just returns either a code
237reference or C<undef> to indicate that no further methods of this name
238exist.
e1a479c5
BB
239
240=head2 maybe::next::method
241
2e4b0c4a 242In simple cases, it is equivalent to:
e1a479c5
BB
243
244 $self->next::method(@_) if $self->next_can;
245
246But there are some cases where only this solution
2e4b0c4a 247works (like C<goto &maybe::next::method>);
e1a479c5 248
08aeb9f7
BB
249=head1 PERFORMANCE CONSIDERATIONS
250
251Specifying the mro type of a class before setting C<@ISA> will
252be faster than the other way around. Also, making all of your
253C<@ISA> manipulations in a single assignment statement will be
254faster that doing them one by one via C<push> (which is what
255C<use base> does currently).
256
257Examples:
258
259 # The slowest way
260 package Foo;
261 use base qw/A B C/;
262 use mro 'c3';
263
264 # The fastest way
265 # (not exactly equivalent to above,
266 # as base.pm can do other magic)
267 use mro 'c3';
268 use A ();
269 use B ();
270 use C ();
271 our @ISA = qw/A B C/;
272
273Generally speaking, every time C<@ISA> is modified, the MRO
274of that class will be recalculated, because of the way array
275magic works. Pushing multiple items onto C<@ISA> in one push
276statement still counts as multiple modifications. However,
277assigning a list to C<@ISA> only counts as a single
278modification. Thus if you really need to do C<push> as
279opposed to assignment, C<@ISA = (@ISA, qw/A B C/);>
280will still be faster than C<push(@ISA, qw/A B C/);>
281
2e4b0c4a 282=head1 SEE ALSO
e1a479c5
BB
283
284=head2 The original Dylan paper
285
286=over 4
287
288=item L<http://www.webcom.com/haahr/dylan/linearization-oopsla96.html>
289
290=back
291
292=head2 The prototype Perl 6 Object Model uses C3
293
294=over 4
295
296=item L<http://svn.openfoundry.org/pugs/perl5/Perl6-MetaModel/>
297
298=back
299
300=head2 Parrot now uses C3
301
302=over 4
303
304=item L<http://aspn.activestate.com/ASPN/Mail/Message/perl6-internals/2746631>
305
306=item L<http://use.perl.org/~autrijus/journal/25768>
307
308=back
309
310=head2 Python 2.3 MRO related links
311
312=over 4
313
314=item L<http://www.python.org/2.3/mro.html>
315
316=item L<http://www.python.org/2.2.2/descrintro.html#mro>
317
318=back
319
320=head2 C3 for TinyCLOS
321
322=over 4
323
324=item L<http://www.call-with-current-continuation.org/eggs/c3.html>
325
326=back
327
328=head2 Class::C3
329
330=over 4
331
332=item L<Class::C3>
333
334=back
335
336=head1 AUTHOR
337
338Brandon L. Black, E<lt>blblack@gmail.comE<gt>
339
340Based on Stevan Little's L<Class::C3>
341
342=cut