Class::C3 - A pragma to use the C3 method resolution order algortihm

    package A;
    use Class::C3;     
    sub hello { 'A::hello' }

    package B;
    use base 'A';
    use Class::C3;

    package C;
    use base 'A';
    use Class::C3;

    sub hello { 'C::hello' }

    package D;
    use base ('B', 'C');
    use Class::C3;

    # Classic Diamond MI pattern
    #    <A>
    #   /   \
    # <B>   <C>
    #   \   /
    #    <D>

    package main;

    print join ', ' => Class::C3::calculateMRO('Diamond_D') # prints D, B, C, A

    print D->hello() # prints 'C::hello' instead of the standard p5 'A::hello'

    D->can('hello')->();          # can() also works correctly
    UNIVERSAL::can('D', 'hello'); # as does UNIVERSAL::can()

This is currently an experimental pragma to change Perl 5's standard method resolution order from depth-first left-to-right (a.k.a - pre-order) to the more sophisticated C3 method resolution order.

C3 is the name of an algorithm which aims to provide a sane method resolution order under multiple inheritence. It was first introduced in the langauge Dylan (see links in the SEE ALSO section), and then later adopted as the prefered MRO (Method Resolution Order) for the new-style classes in Python 2.3. Most recently it has been adopted as the 'canonical' MRO for Perl 6 classes, and the default MRO for Parrot objects as well.

C3 works by always preserving local precendence ordering. This essentially means that no class will appear before any of it's subclasses. Take the classic diamond inheritence pattern for instance:

     <A>
    /   \
  <B>   <C>
    \   /
     <D>

The standard Perl 5 MRO would be (D, B, A, C). The result being that A appears before C, even though C is the subclass of A. The C3 MRO algorithm however, produces the following MRO (D, B, C, A), which does not have this same issue.

This example is fairly trival, for more complex examples and a deeper explaination, see the links in the SEE ALSO section.

This module uses a technique similar to Perl 5's method caching. During the INIT phase, this module calculates the MRO of all the classes which called CWuse Class::C3. It then gathers information from the symbol tables of each of those classes, and builds a set of method aliases for the correct dispatch ordering. Once all these C3-based method tables are created, it then adds the method aliases into the local classes symbol table.

The end result is actually classes with pre-cached method dispatch. However, this caching does not do well if you start changing your CW@ISA or messing with class symbol tables, so you should consider your classes to be effectively closed. See the CAVEATS section for more details.

This release also includes an optional module c3 in the opt/ folder. I did not include this in the regular install since lowercase module names are considered bad by some people. However I think that code looks much nicer like this:

  package MyClass;
  use c3;

The the more clunky:

  package MyClass;
  use Class::C3;

But hey, it's your choice, thats why it is optional.

calculateMRO ($class)

Given a CW$class this will return an array of class names in the proper C3 method resolution order.

initialize

This can be used to initalize the C3 method dispatch tables. You need to call this if you are running under mod_perl, or in any other environment which does not run the INIT phase of the perl compiler. NOTE: This can not be used to re-load the dispatch tables for all classes. Use CWreinitialize for that.

uninitialize

Calling this function results in the removal of all cached methods, and the restoration of the old Perl 5 style dispatch order (depth-first, left-to-right).

reinitialize

This effectively calls CWuninitialize followed by CWinitialize the result of which is a reloading of all the calculated C3 dispatch tables. It should be noted that if you have a large class library, this could potentially be a rather costly operation.

It is always useful to be able to re-dispatch your method call to the next most applicable method. This module provides a pseudo package along the lines of CWSUPER:: or CWNEXT:: which will re-dispatch the method along the C3 linearization. This is best show with an examples.

  # a classic diamond MI pattern ...
     <A>
    /   \
  <B>   <C>
    \   /
     <D>

  package A;
  use c3; 
  sub foo { 'A::foo' }

  package B;
  use base 'A'; 
  use c3;     
  sub foo { 'B::foo => ' . (shift)->next::method() }

  package B;
  use base 'A'; 
  use c3;    
  sub foo { 'C::foo => ' . (shift)->next::method() }

  package D;
  use base ('B', 'C'); 
  use c3; 
  sub foo { 'D::foo => ' . (shift)->next::method() }

  print D->foo; # prints out "D::foo => B::foo => C::foo => A::foo"

A few things to note. First, we do not require you to add on the method name to the CWnext::method call (this is unlike CWNEXT:: and CWSUPER:: which do require that). This helps to enforce the rule that you cannot dispatch to a method of a different name (this is how CWNEXT:: behaves as well).

The next thing to keep in mind is that you will need to pass all arguments to CWnext::method it can not automatically use the current CW@_.

Let me first say, this is an experimental module, and so it should not be used for anything other then other experimentation for the time being.

That said, it is the authors intention to make this into a completely usable and production stable module if possible. Time will tell.

And now, onto the caveats. The idea of CWSUPER:: under multiple inheritence is ambigious, and generally not recomended anyway. However, it's use in conjuntion with this module is very much not recommended, and in fact very discouraged. The recommended approach is to instead use the supplied CWnext::method feature, see more details on it's usage above. It is the author's opinion that changing CW@ISA at runtime is pure insanity anyway. However, people do it, so I must caveat. Any changes to the CW@ISA will not be reflected in the MRO calculated by this module, and therefor probably won't even show up. If you do this, you will need to call CWreinitialize in order to recalulate all method dispatch tables. See the CWreinitialize documentation and an example in t/20_reinitialize.t for more information.

Adding/deleting methods from class symbol tables.

This module calculates the MRO for each requested class during the INIT phase by interogatting the symbol tables of said classes. So any symbol table manipulation which takes place after our INIT phase is run will not be reflected in the calculated MRO. Just as with changing the CW@ISA, you will need to call CWreinitialize for any changes you make to take effect.

More tests

You can never have enough tests :)

I use Devel::Cover to test the code coverage of my tests, below is the Devel::Cover report on this module's test suite.

 ---------------------------- ------ ------ ------ ------ ------ ------ ------
 File                           stmt   bran   cond    sub    pod   time  total
 ---------------------------- ------ ------ ------ ------ ------ ------ ------
 Class/C3.pm                    98.6   90.9   73.3   96.0  100.0   96.8   95.3
 ---------------------------- ------ ------ ------ ------ ------ ------ ------
 Total                          98.6   90.9   73.3   96.0  100.0   96.8   95.3
 ---------------------------- ------ ------ ------ ------ ------ ------ ------

<http://www.webcom.com/haahr/dylan/linearization-oopsla96.html>

<http://svn.openfoundry.org/pugs/perl5/Perl6-MetaModel/>

<http://aspn.activestate.com/ASPN/Mail/Message/perl6-internals/2746631>

<http://use.perl.org/~autrijus/journal/25768>

<http://www.python.org/2.3/mro.html>

<http://www.python.org/2.2.2/descrintro.html#mro>

<http://www.call-with-current-continuation.org/eggs/c3.html>

Thanks to Matt S. Trout for using this module in his module DBIx::Class and finding many bugs and providing fixes.

Stevan Little, <stevan@iinteractive.com>

Copyright 2005 by Infinity Interactive, Inc.

<http://www.iinteractive.com>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.