lib/mro.pm

   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
  30   use mro 'dfs'; # enable DFS MRO for this class (Perl default)
  31   use mro 'c3'; # enable C3 MRO for this class
  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
  38 =head1 OVERVIEW
  39
  40 It's possible to change the MRO of a given class either by using C<use
  41 mro> as shown in the synopsis, or by using the L</mro::set_mro> function
  42 below.  The functions do not require loading the C<mro> module, as they
  43 are actually provided by the core perl interpreter.  The C<use mro> syntax
  44 is just syntactic sugar for setting the current package's MRO.
  45
  46 =head1 The C3 MRO
  47
  48 In addition to the traditional Perl default MRO (depth first
  49 search, called C<DFS> here), Perl now offers the C3 MRO as
  50 well.  Perl's support for C3 is based on the work done in
  51 Stevan Little's module L<Class::C3>, and most of the C3-related
  52 documentation here is ripped directly from there.
  53
  54 =head2 What is C3?
  55
  56 C3 is the name of an algorithm which aims to provide a sane method
  57 resolution order under multiple inheritance. It was first introduced in
  58 the language Dylan (see links in the L</"SEE ALSO"> section), and then
  59 later adopted as the preferred MRO (Method Resolution Order) for the
  60 new-style classes in Python 2.3. Most recently it has been adopted as the
  61 "canonical" MRO for Perl 6 classes, and the default MRO for Parrot objects
  62 as well.
  63
  64 =head2 How does C3 work
  65
  66 C3 works by always preserving local precendence ordering. This essentially
  67 means that no class will appear before any of its subclasses. Take, for
  68 instance, the classic diamond inheritance pattern:
  69
  70      <A>
  71     /   \
  72   <B>   <C>
  73     \   /
  74      <D>
  75
  76 The standard Perl 5 MRO would be (D, B, A, C). The result being that B<A>
  77 appears before B<C>, even though B<C> is the subclass of B<A>. The C3 MRO
  78 algorithm however, produces the following order: (D, B, C, A), which does
  79 not have this issue.
  80
  81 This example is fairly trivial; for more complex cases and a deeper
  82 explanation, see the links in the L</"SEE ALSO"> section.
  83
  84 =head1 Functions
  85
  86 =head2 mro::get_linear_isa($classname[, $type])
  87
  88 Returns an arrayref which is the linearized MRO of the given class.
  89 Uses whichever MRO is currently in effect for that class by default,
  90 or the given MRO (either C<c3> or C<dfs> if specified as C<$type>).
  91
  92 Note that C<UNIVERSAL> (and any members of C<UNIVERSAL>'s MRO) are not
  93 part of the MRO of a class, even though all classes implicitly inherit
  94 methods from C<UNIVERSAL> and its parents.
  95
  96 =head2 mro::set_mro($classname, $type)
  97
  98 Sets the MRO of the given class to the C<$type> argument (either
  99 C<c3> or C<dfs>).
 100
 101 =head2 mro::get_mro($classname)
 102
 103 Returns the MRO of the given class (either C<c3> or C<dfs>).
 104
 105 =head2 mro::get_isarev($classname)
 106
 107 Gets the C<mro_isarev> for this class, returned as an
 108 array of class names.  These are every class that "isa"
 109 the given class name, even if the isa relationship is
 110 indirect.  This is used internally by the MRO code to
 111 keep track of method/MRO cache invalidations.
 112
 113 Currently, this list only grows, it never shrinks.  This
 114 was a performance consideration (properly tracking and
 115 deleting isarev entries when someone removes an entry
 116 from an C<@ISA> is costly, and it doesn't happen often
 117 anyways).  The fact that a class which no longer truly
 118 "isa" this class at runtime remains on the list should be
 119 considered a quirky implementation detail which is subject
 120 to future change.  It shouldn't be an issue as long as
 121 you're looking at this list for the same reasons the
 122 core code does: as a performance optimization
 123 over having to search every class in existence.
 124
 125 As with C<mro::get_mro> above, C<UNIVERSAL> is special.
 126 C<UNIVERSAL> (and parents') isarev lists do not include
 127 every class in existence, even though all classes are
 128 effectively descendants for method inheritance purposes.
 129
 130 =head2 mro::is_universal($classname)
 131
 132 Returns a boolean status indicating whether or not
 133 the given classname is either C<UNIVERSAL> itself,
 134 or one of C<UNIVERSAL>'s parents by C<@ISA> inheritance.
 135
 136 Any class for which this function returns true is
 137 "universal" in the sense that all classes potentially
 138 inherit methods from it.
 139
 140 For similar reasons to C<isarev> above, this flag is
 141 permanent.  Once it is set, it does not go away, even
 142 if the class in question really isn't universal anymore.
 143
 144 =head2 mro::get_global_sub_generation()
 145
 146 Returns the current value of the internal perl variable
 147 C<PL_sub_generation>.
 148
 149 =head2 mro::invalidate_all_method_caches()
 150
 151 Increments C<PL_sub_generation>, which invalidates method
 152 caching in all packages.
 153
 154 =head2 mro::get_sub_generation($classname)
 155
 156 Returns the current value of a given package's C<sub_generation>.
 157 This is only incremented when necessary for that package.
 158
 159 If one is trying to determine whether significant (method/cache-affecting)
 160 changes have occured for a given stash since you last checked, you should
 161 check both this and the global one above.
 162
 163 =head2 mro::method_changed_in($classname)
 164
 165 Invalidates the method cache of any classes dependent on the
 166 given class.
 167
 168 =head2 next::method
 169
 170 This is somewhat like C<SUPER>, but it uses the C3 method
 171 resolution order to get better consistency in multiple
 172 inheritance situations.  Note that while inheritance in
 173 general follows whichever MRO is in effect for the
 174 given class, C<next::method> only uses the C3 MRO.
 175
 176 One generally uses it like so:
 177
 178   sub some_method {
 179     my $self = shift;
 180     my $superclass_answer = $self->next::method(@_);
 181     return $superclass_answer + 1;
 182   }
 183
 184 Note that you don't (re-)specify the method name.
 185 It forces you to always use the same method name
 186 as the method you started in.
 187
 188 It can be called on an object or a class, of course.
 189
 190 The way it resolves which actual method to call is:
 191
 192 =over 4
 193
 194 =item 1
 195
 196 First, it determines the linearized C3 MRO of
 197 the object or class it is being called on.
 198
 199 =item 2
 200
 201 Then, it determines the class and method name
 202 of the context it was invoked from.
 203
 204 =item 3
 205
 206 Finally, it searches down the C3 MRO list until
 207 it reaches the contextually enclosing class, then
 208 searches further down the MRO list for the next
 209 method with the same name as the contextually
 210 enclosing method.
 211
 212 =back
 213
 214 Failure to find a next method will result in an
 215 exception being thrown (see below for alternatives).
 216
 217 This is substantially different than the behavior
 218 of C<SUPER> under complex multiple inheritance.
 219 (This becomes obvious when one realizes that the
 220 common superclasses in the C3 linearizations of
 221 a given class and one of its parents will not
 222 always be ordered the same for both.)
 223
 224 B<Caveat>: Calling C<next::method> from methods defined outside the class:
 225
 226 There is an edge case when using C<next::method> from within a subroutine
 227 which was created in a different module than the one it is called from. It
 228 sounds complicated, but it really isn't. Here is an example which will not
 229 work correctly:
 230
 231   *Foo::foo = sub { (shift)->next::method(@_) };
 232
 233 The problem exists because the anonymous subroutine being assigned to the
 234 C<*Foo::foo> glob will show up in the call stack as being called
 235 C<__ANON__> and not C<foo> as you might expect. Since C<next::method> uses
 236 C<caller> to find the name of the method it was called in, it will fail in
 237 this case.
 238
 239 But fear not, there's a simple solution. The module C<Sub::Name> will
 240 reach into the perl internals and assign a name to an anonymous subroutine
 241 for you. Simply do this:
 242
 243   use Sub::Name 'subname';
 244   *Foo::foo = subname 'Foo::foo' => sub { (shift)->next::method(@_) };
 245
 246 and things will Just Work.
 247
 248 =head2 next::can
 249
 250 This is similar to C<next::method>, but just returns either a code
 251 reference or C<undef> to indicate that no further methods of this name
 252 exist.
 253
 254 =head2 maybe::next::method
 255
 256 In simple cases, it is equivalent to:
 257
 258    $self->next::method(@_) if $self->next_can;
 259
 260 But there are some cases where only this solution
 261 works (like C<goto &maybe::next::method>);
 262
 263 =head1 SEE ALSO
 264
 265 =head2 The original Dylan paper
 266
 267 =over 4
 268
 269 =item L<http://www.webcom.com/haahr/dylan/linearization-oopsla96.html>
 270
 271 =back
 272
 273 =head2 The prototype Perl 6 Object Model uses C3
 274
 275 =over 4
 276
 277 =item L<http://svn.openfoundry.org/pugs/perl5/Perl6-MetaModel/>
 278
 279 =back
 280
 281 =head2 Parrot now uses C3
 282
 283 =over 4
 284
 285 =item L<http://aspn.activestate.com/ASPN/Mail/Message/perl6-internals/2746631>
 286
 287 =item L<http://use.perl.org/~autrijus/journal/25768>
 288
 289 =back
 290
 291 =head2 Python 2.3 MRO related links
 292
 293 =over 4
 294
 295 =item L<http://www.python.org/2.3/mro.html>
 296
 297 =item L<http://www.python.org/2.2.2/descrintro.html#mro>
 298
 299 =back
 300
 301 =head2 C3 for TinyCLOS
 302
 303 =over 4
 304
 305 =item L<http://www.call-with-current-continuation.org/eggs/c3.html>
 306
 307 =back
 308
 309 =head2 Class::C3
 310
 311 =over 4
 312
 313 =item L<Class::C3>
 314
 315 =back
 316
 317 =head1 AUTHOR
 318
 319 Brandon L. Black, E<lt>blblack@gmail.comE<gt>
 320
 321 Based on Stevan Little's L<Class::C3>
 322
 323 =cut