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