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