1Class::C3(3)          User Contributed Perl Documentation         Class::C3(3)
2
3
4

NAME

6       Class::C3 - A pragma to use the C3 method resolution order algorithm
7

SYNOPSIS

9           # NOTE - DO NOT USE Class::C3 directly as a user, use MRO::Compat instead!
10           package ClassA;
11           use Class::C3;
12           sub hello { 'A::hello' }
13
14           package ClassB;
15           use base 'ClassA';
16           use Class::C3;
17
18           package ClassC;
19           use base 'ClassA';
20           use Class::C3;
21
22           sub hello { 'C::hello' }
23
24           package ClassD;
25           use base ('ClassB', 'ClassC');
26           use Class::C3;
27
28           # Classic Diamond MI pattern
29           #    <A>
30           #   /   \
31           # <B>   <C>
32           #   \   /
33           #    <D>
34
35           package main;
36
37           # initializez the C3 module
38           # (formerly called in INIT)
39           Class::C3::initialize();
40
41           print join ', ' => Class::C3::calculateMRO('ClassD'); # prints ClassD, ClassB, ClassC, ClassA
42
43           print ClassD->hello(); # prints 'C::hello' instead of the standard p5 'A::hello'
44
45           ClassD->can('hello')->();          # can() also works correctly
46           UNIVERSAL::can('ClassD', 'hello'); # as does UNIVERSAL::can()
47

DESCRIPTION

49       This is pragma to change Perl 5's standard method resolution order from
50       depth-first left-to-right (a.k.a - pre-order) to the more sophisticated
51       C3 method resolution order.
52
53       NOTE: YOU SHOULD NOT USE THIS MODULE DIRECTLY - The feature provided is
54       integrated into perl version >= 5.9.5, and you should use MRO::Compat
55       instead, which will use the core implementation in newer perls, but
56       fallback to using this implementation on older perls.
57
58   What is C3?
59       C3 is the name of an algorithm which aims to provide a sane method
60       resolution order under multiple inheritance. It was first introduced in
61       the language Dylan (see links in the "SEE ALSO" section), and then
62       later adopted as the preferred MRO (Method Resolution Order) for the
63       new-style classes in Python 2.3. Most recently it has been adopted as
64       the 'canonical' MRO for Perl 6 classes, and the default MRO for Parrot
65       objects as well.
66
67   How does C3 work.
68       C3 works by always preserving local precedence ordering. This
69       essentially means that no class will appear before any of its
70       subclasses. Take the classic diamond inheritance pattern for instance:
71
72            <A>
73           /   \
74         <B>   <C>
75           \   /
76            <D>
77
78       The standard Perl 5 MRO would be (D, B, A, C). The result being that A
79       appears before C, even though C is the subclass of A. The C3 MRO
80       algorithm however, produces the following MRO (D, B, C, A), which does
81       not have this same issue.
82
83       This example is fairly trivial, for more complex examples and a deeper
84       explanation, see the links in the "SEE ALSO" section.
85
86   How does this module work?
87       This module uses a technique similar to Perl 5's method caching. When
88       "Class::C3::initialize" is called, this module calculates the MRO of
89       all the classes which called "use Class::C3". It then gathers
90       information from the symbol tables of each of those classes, and builds
91       a set of method aliases for the correct dispatch ordering. Once all
92       these C3-based method tables are created, it then adds the method
93       aliases into the local classes symbol table.
94
95       The end result is actually classes with pre-cached method dispatch.
96       However, this caching does not do well if you start changing your @ISA
97       or messing with class symbol tables, so you should consider your
98       classes to be effectively closed. See the CAVEATS section for more
99       details.
100

OPTIONAL LOWERCASE PRAGMA

102       This release also includes an optional module c3 in the opt/ folder. I
103       did not include this in the regular install since lowercase module
104       names are considered "bad" by some people. However I think that code
105       looks much nicer like this:
106
107         package MyClass;
108         use c3;
109
110       This is more clunky:
111
112         package MyClass;
113         use Class::C3;
114
115       But hey, it's your choice, that's why it is optional.
116

FUNCTIONS

118       calculateMRO ($class)
119           Given a $class this will return an array of class names in the
120           proper C3 method resolution order.
121
122       initialize
123           This must be called to initialize the C3 method dispatch tables,
124           this module will not work if you do not do this. It is advised to
125           do this as soon as possible after loading any classes which use C3.
126           Here is a quick code example:
127
128             package Foo;
129             use Class::C3;
130             # ... Foo methods here
131
132             package Bar;
133             use Class::C3;
134             use base 'Foo';
135             # ... Bar methods here
136
137             package main;
138
139             Class::C3::initialize(); # now it is safe to use Foo and Bar
140
141           This function used to be called automatically for you in the INIT
142           phase of the perl compiler, but that lead to warnings if this
143           module was required at runtime. After discussion with my user base
144           (the DBIx::Class folks), we decided that calling this in INIT was
145           more of an annoyance than a convenience. I apologize to anyone this
146           causes problems for (although I would be very surprised if I had
147           any other users other than the DBIx::Class folks). The simplest
148           solution of course is to define your own INIT method which calls
149           this function.
150
151           NOTE:
152
153           If "initialize" detects that "initialize" has already been
154           executed, it will "uninitialize" and clear the MRO cache first.
155
156       uninitialize
157           Calling this function results in the removal of all cached methods,
158           and the restoration of the old Perl 5 style dispatch order (depth-
159           first, left-to-right).
160
161       reinitialize
162           This is an alias for "initialize" above.
163

METHOD REDISPATCHING

165       It is always useful to be able to re-dispatch your method call to the
166       "next most applicable method". This module provides a pseudo package
167       along the lines of "SUPER::" or "NEXT::" which will re-dispatch the
168       method along the C3 linearization. This is best shown with an example.
169
170         # a classic diamond MI pattern ...
171         #    <A>
172         #   /   \
173         # <B>   <C>
174         #   \   /
175         #    <D>
176
177         package ClassA;
178         use Class::C3;
179         sub foo { 'ClassA::foo' }
180
181         package ClassB;
182         use base 'ClassA';
183         use Class::C3;
184         sub foo { 'ClassB::foo => ' . (shift)->next::method() }
185
186         package ClassC;
187         use base 'ClassA';
188         use Class::C3;
189         sub foo { 'ClassC::foo => ' . (shift)->next::method() }
190
191         package ClassD;
192         use base ('ClassB', 'ClassC');
193         use Class::C3;
194         sub foo { 'ClassD::foo => ' . (shift)->next::method() }
195
196         print ClassD->foo; # prints out "ClassD::foo => ClassB::foo => ClassC::foo => ClassA::foo"
197
198       A few things to note. First, we do not require you to add on the method
199       name to the "next::method" call (this is unlike "NEXT::" and "SUPER::"
200       which do require that). This helps to enforce the rule that you cannot
201       dispatch to a method of a different name (this is how "NEXT::" behaves
202       as well).
203
204       The next thing to keep in mind is that you will need to pass all
205       arguments to "next::method".  It can not automatically use the current
206       @_.
207
208       If "next::method" cannot find a next method to re-dispatch the call to,
209       it will throw an exception.  You can use "next::can" to see if
210       "next::method" will succeed before you call it like so:
211
212         $self->next::method(@_) if $self->next::can;
213
214       Additionally, you can use "maybe::next::method" as a shortcut to only
215       call the next method if it exists.  The previous example could be
216       simply written as:
217
218         $self->maybe::next::method(@_);
219
220       There are some caveats about using "next::method", see below for those.
221

CAVEATS

223       This module used to be labeled as experimental, however it has now been
224       pretty heavily tested by the good folks over at DBIx::Class and I am
225       confident this module is perfectly usable for whatever your needs might
226       be.
227
228       But there are still caveats, so here goes ...
229
230       Use of "SUPER::".
231           The idea of "SUPER::" under multiple inheritance is ambiguous, and
232           generally not recommended anyway.  However, its use in conjunction
233           with this module is very much not recommended, and in fact very
234           discouraged. The recommended approach is to instead use the
235           supplied "next::method" feature, see more details on its usage
236           above.
237
238       Changing @ISA.
239           It is the author's opinion that changing @ISA at runtime is pure
240           insanity anyway. However, people do it, so I must caveat. Any
241           changes to the @ISA will not be reflected in the MRO calculated by
242           this module, and therefore probably won't even show up. If you do
243           this, you will need to call "reinitialize" in order to recalculate
244           all method dispatch tables. See the "reinitialize" documentation
245           and an example in t/20_reinitialize.t for more information.
246
247       Adding/deleting methods from class symbol tables.
248           This module calculates the MRO for each requested class by
249           interrogating the symbol tables of said classes.  So any symbol
250           table manipulation which takes place after our INIT phase is run
251           will not be reflected in the calculated MRO. Just as with changing
252           the @ISA, you will need to call "reinitialize" for any changes you
253           make to take effect.
254
255       Calling "next::method" from methods defined outside the class
256           There is an edge case when using "next::method" from within a
257           subroutine which was created in a different module than the one it
258           is called from. It sounds complicated, but it really isn't. Here is
259           an example which will not work correctly:
260
261             *Foo::foo = sub { (shift)->next::method(@_) };
262
263           The problem exists because the anonymous subroutine being assigned
264           to the glob *Foo::foo will show up in the call stack as being
265           called "__ANON__" and not "foo" as you might expect. Since
266           "next::method" uses "caller" to find the name of the method it was
267           called in, it will fail in this case.
268
269           But fear not, there is a simple solution. The module "Sub::Name"
270           will reach into the perl internals and assign a name to an
271           anonymous subroutine for you. Simply do this:
272
273             use Sub::Name 'subname';
274             *Foo::foo = subname 'Foo::foo' => sub { (shift)->next::method(@_) };
275
276           and things will Just Work. Of course this is not always possible to
277           do, but to be honest, I just can't manage to find a workaround for
278           it, so until someone gives me a working patch this will be a known
279           limitation of this module.
280

COMPATIBILITY

282       If your software requires Perl 5.9.5 or higher, you do not need
283       Class::C3, you can simply "use mro 'c3'", and not worry about
284       "initialize()", avoid some of the above caveats, and get the best
285       possible performance.  See mro for more details.
286
287       If your software is meant to work on earlier Perls, use Class::C3 as
288       documented here.  Class::C3 will detect Perl 5.9.5+ and take advantage
289       of the core support when available.
290

Class::C3::XS

292       This module will load Class::C3::XS if it's installed and you are
293       running on a Perl version older than 5.9.5.  The optional module will
294       be automatically installed for you if a C compiler is available, as it
295       results in significant performance improvements (but unlike the 5.9.5+
296       core support, it still has all of the same caveats as Class::C3).
297

CODE COVERAGE

299       Devel::Cover was reporting 94.4% overall test coverage earlier in this
300       module's life.  Currently, the test suite does things that break under
301       coverage testing, but it is fair to assume the coverage is still close
302       to that value.
303

SEE ALSO

305   The original Dylan paper
306       <https://web.archive.org/web/20000817033012id_/http://www.webcom.com/haahr/dylan/linearization-oopsla96.html>
307
308   The prototype Perl 6 Object Model uses C3
309       <http://svn.openfoundry.org/pugs/perl5/Perl6-MetaModel/>
310
311   Parrot now uses C3
312       <http://aspn.activestate.com/ASPN/Mail/Message/perl6-internals/2746631>
313       <http://use.perl.org/~autrijus/journal/25768>
314
315   Python 2.3 MRO related links
316       <http://www.python.org/2.3/mro.html>
317       <http://www.python.org/2.2.2/descrintro.html#mro>
318
319   C3 for TinyCLOS
320       <http://www.call-with-current-continuation.org/eggs/c3.html>
321

ACKNOWLEGEMENTS

323       Thanks to Matt S. Trout for using this module in his module DBIx::Class
324       and finding many bugs and providing fixes.
325       Thanks to Justin Guenther for making "next::method" more robust by
326       handling calls inside "eval" and anon-subs.
327       Thanks to Robert Norris for adding support for "next::can" and
328       "maybe::next::method".
329

AUTHOR

331       Stevan Little, <stevan@iinteractive.com>
332
333       Brandon L. Black, <blblack@gmail.com>
334
336       Copyright 2005, 2006 by Infinity Interactive, Inc.
337
338       <http://www.iinteractive.com>
339
340       This library is free software; you can redistribute it and/or modify it
341       under the same terms as Perl itself.
342
343
344
345perl v5.36.0                      2022-07-22                      Class::C3(3)
Impressum