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