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.14';
  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 occurrence, 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 the 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