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