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