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