mingw/html/lib/NEXT.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>NEXT.pm - Provide a pseudo-class NEXT that allows method redispatch</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;NEXT.pm - Provide a pseudo-class NEXT that allows method redispatch</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <ul>
  26
  27                 <li><a href="#enforcing_redispatch">Enforcing redispatch</a></li>
  28                 <li><a href="#avoiding_repetitions">Avoiding repetitions</a></li>
  29                 <li><a href="#invoking_all_versions_of_a_method_with_a_single_call">Invoking all versions of a method with a single call</a></li>
  30                 <li><a href="#using_every_methods">Using <code>EVERY</code> methods</a></li>
  31         </ul>
  32
  33         <li><a href="#author">AUTHOR</a></li>
  34         <li><a href="#bugs_and_irritations">BUGS AND IRRITATIONS</a></li>
  35         <li><a href="#copyright">COPYRIGHT</a></li>
  36 </ul>
  37 <!-- INDEX END -->
  38
  39 <hr />
  40 <p>
  41 </p>
  42 <h1><a name="name">NAME</a></h1>
  43 <p>NEXT.pm - Provide a pseudo-class NEXT (et al) that allows method redispatch</p>
  44 <p>
  45 </p>
  46 <hr />
  47 <h1><a name="synopsis">SYNOPSIS</a></h1>
  48 <pre>
  49     use NEXT;</pre>
  50 <pre>
  51     package A;
  52     sub A::method   { print &quot;$_[0]: A method\n&quot;;   $_[0]-&gt;NEXT::method() }
  53     sub A::DESTROY  { print &quot;$_[0]: A dtor\n&quot;;     $_[0]-&gt;NEXT::DESTROY() }</pre>
  54 <pre>
  55     package B;
  56     use base qw( A );
  57     sub B::AUTOLOAD { print &quot;$_[0]: B AUTOLOAD\n&quot;; $_[0]-&gt;NEXT::AUTOLOAD() }
  58     sub B::DESTROY  { print &quot;$_[0]: B dtor\n&quot;;     $_[0]-&gt;NEXT::DESTROY() }</pre>
  59 <pre>
  60     package C;
  61     sub C::method   { print &quot;$_[0]: C method\n&quot;;   $_[0]-&gt;NEXT::method() }
  62     sub C::AUTOLOAD { print &quot;$_[0]: C AUTOLOAD\n&quot;; $_[0]-&gt;NEXT::AUTOLOAD() }
  63     sub C::DESTROY  { print &quot;$_[0]: C dtor\n&quot;;     $_[0]-&gt;NEXT::DESTROY() }</pre>
  64 <pre>
  65     package D;
  66     use base qw( B C );
  67     sub D::method   { print &quot;$_[0]: D method\n&quot;;   $_[0]-&gt;NEXT::method() }
  68     sub D::AUTOLOAD { print &quot;$_[0]: D AUTOLOAD\n&quot;; $_[0]-&gt;NEXT::AUTOLOAD() }
  69     sub D::DESTROY  { print &quot;$_[0]: D dtor\n&quot;;     $_[0]-&gt;NEXT::DESTROY() }</pre>
  70 <pre>
  71     package main;</pre>
  72 <pre>
  73     my $obj = bless {}, &quot;D&quot;;</pre>
  74 <pre>
  75     $obj-&gt;method();             # Calls D::method, A::method, C::method
  76     $obj-&gt;missing_method(); # Calls D::AUTOLOAD, B::AUTOLOAD, C::AUTOLOAD</pre>
  77 <pre>
  78     # Clean-up calls D::DESTROY, B::DESTROY, A::DESTROY, C::DESTROY</pre>
  79 <p>
  80 </p>
  81 <hr />
  82 <h1><a name="description">DESCRIPTION</a></h1>
  83 <p>NEXT.pm adds a pseudoclass named <code>NEXT</code> to any program
  84 that uses it. If a method <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_m"><code>m</code></a> calls <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_m"><code>$self-&gt;NEXT::m()</code></a>, the call to
  85 <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_m"><code>m</code></a> is redispatched as if the calling method had not originally been found.</p>
  86 <p>In other words, a call to <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_m"><code>$self-&gt;NEXT::m()</code></a> resumes the depth-first,
  87 left-to-right search of <code>$self</code>'s class hierarchy that resulted in the
  88 original call to <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_m"><code>m</code></a>.</p>
  89 <p>Note that this is not the same thing as <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_m"><code>$self-&gt;SUPER::m()</code></a>, which
  90 begins a new dispatch that is restricted to searching the ancestors
  91 of the current class. <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_m"><code>$self-&gt;NEXT::m()</code></a> can backtrack
  92 past the current class -- to look for a suitable method in other
  93 ancestors of <code>$self</code> -- whereas <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_m"><code>$self-&gt;SUPER::m()</code></a> cannot.</p>
  94 <p>A typical use would be in the destructors of a class hierarchy,
  95 as illustrated in the synopsis above. Each class in the hierarchy
  96 has a DESTROY method that performs some class-specific action
  97 and then redispatches the call up the hierarchy. As a result,
  98 when an object of class D is destroyed, the destructors of <em>all</em>
  99 its parent classes are called (in depth-first, left-to-right order).</p>
 100 <p>Another typical use of redispatch would be in <code>AUTOLOAD</code>'ed methods.
 101 If such a method determined that it was not able to handle a
 102 particular call, it might choose to redispatch that call, in the
 103 hope that some other <code>AUTOLOAD</code> (above it, or to its left) might
 104 do better.</p>
 105 <p>By default, if a redispatch attempt fails to find another method
 106 elsewhere in the objects class hierarchy, it quietly gives up and does
 107 nothing (but see <a href="#enforcing_redispatch">Enforcing redispatch</a>). This gracious acquiesence
 108 is also unlike the (generally annoying) behaviour of <code>SUPER</code>, which
 109 throws an exception if it cannot redispatch.</p>
 110 <p>Note that it is a fatal error for any method (including <code>AUTOLOAD</code>)
 111 to attempt to redispatch any method that does not have the
 112 same name. For example:</p>
 113 <pre>
 114         sub D::oops { print &quot;oops!\n&quot;; $_[0]-&gt;NEXT::other_method() }</pre>
 115 <p>
 116 </p>
 117 <h2><a name="enforcing_redispatch">Enforcing redispatch</a></h2>
 118 <p>It is possible to make <code>NEXT</code> redispatch more demandingly (i.e. like
 119 <code>SUPER</code> does), so that the redispatch throws an exception if it cannot
 120 find a ``next'' method to call.</p>
 121 <p>To do this, simple invoke the redispatch as:</p>
 122 <pre>
 123         $self-&gt;NEXT::ACTUAL::method();</pre>
 124 <p>rather than:</p>
 125 <pre>
 126         $self-&gt;NEXT::method();</pre>
 127 <p>The <code>ACTUAL</code> tells <code>NEXT</code> that there must actually be a next method to call,
 128 or it should throw an exception.</p>
 129 <p><code>NEXT::ACTUAL</code> is most commonly used in <code>AUTOLOAD</code> methods, as a means to
 130 decline an <code>AUTOLOAD</code> request, but preserve the normal exception-on-failure
 131 semantics:</p>
 132 <pre>
 133         sub AUTOLOAD {
 134                 if ($AUTOLOAD =~ /foo|bar/) {
 135                         # handle here
 136                 }
 137                 else {  # try elsewhere
 138                         shift()-&gt;NEXT::ACTUAL::AUTOLOAD(@_);
 139                 }
 140         }</pre>
 141 <p>By using <code>NEXT::ACTUAL</code>, if there is no other <code>AUTOLOAD</code> to handle the
 142 method call, an exception will be thrown (as usually happens in the absence of
 143 a suitable <code>AUTOLOAD</code>).</p>
 144 <p>
 145 </p>
 146 <h2><a name="avoiding_repetitions">Avoiding repetitions</a></h2>
 147 <p>If <code>NEXT</code> redispatching is used in the methods of a ``diamond'' class hierarchy:</p>
 148 <pre>
 149         #     A   B
 150         #    / \ /
 151         #   C   D
 152         #    \ /
 153         #     E</pre>
 154 <pre>
 155         use NEXT;</pre>
 156 <pre>
 157         package A;
 158         sub foo { print &quot;called A::foo\n&quot;; shift-&gt;NEXT::foo() }</pre>
 159 <pre>
 160         package B;
 161         sub foo { print &quot;called B::foo\n&quot;; shift-&gt;NEXT::foo() }</pre>
 162 <pre>
 163         package C; @ISA = qw( A );
 164         sub foo { print &quot;called C::foo\n&quot;; shift-&gt;NEXT::foo() }</pre>
 165 <pre>
 166         package D; @ISA = qw(A B);
 167         sub foo { print &quot;called D::foo\n&quot;; shift-&gt;NEXT::foo() }</pre>
 168 <pre>
 169         package E; @ISA = qw(C D);
 170         sub foo { print &quot;called E::foo\n&quot;; shift-&gt;NEXT::foo() }</pre>
 171 <pre>
 172         E-&gt;foo();</pre>
 173 <p>then derived classes may (re-)inherit base-class methods through two or
 174 more distinct paths (e.g. in the way <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_e"><code>E</code></a> inherits <code>A::foo</code> twice --
 175 through <code>C</code> and <code>D</code>). In such cases, a sequence of <code>NEXT</code> redispatches
 176 will invoke the multiply inherited method as many times as it is
 177 inherited. For example, the above code prints:</p>
 178 <pre>
 179         called E::foo
 180         called C::foo
 181         called A::foo
 182         called D::foo
 183         called A::foo
 184         called B::foo</pre>
 185 <p>(i.e. <code>A::foo</code> is called twice).</p>
 186 <p>In some cases this <em>may</em> be the desired effect within a diamond hierarchy,
 187 but in others (e.g. for destructors) it may be more appropriate to
 188 call each method only once during a sequence of redispatches.</p>
 189 <p>To cover such cases, you can redispatch methods via:</p>
 190 <pre>
 191         $self-&gt;NEXT::DISTINCT::method();</pre>
 192 <p>rather than:</p>
 193 <pre>
 194         $self-&gt;NEXT::method();</pre>
 195 <p>This causes the redispatcher to only visit each distinct <code>method</code> method
 196 once. That is, to skip any classes in the hierarchy that it has
 197 already visited during redispatch. So, for example, if the
 198 previous example were rewritten:</p>
 199 <pre>
 200         package A;
 201         sub foo { print &quot;called A::foo\n&quot;; shift-&gt;NEXT::DISTINCT::foo() }</pre>
 202 <pre>
 203         package B;
 204         sub foo { print &quot;called B::foo\n&quot;; shift-&gt;NEXT::DISTINCT::foo() }</pre>
 205 <pre>
 206         package C; @ISA = qw( A );
 207         sub foo { print &quot;called C::foo\n&quot;; shift-&gt;NEXT::DISTINCT::foo() }</pre>
 208 <pre>
 209         package D; @ISA = qw(A B);
 210         sub foo { print &quot;called D::foo\n&quot;; shift-&gt;NEXT::DISTINCT::foo() }</pre>
 211 <pre>
 212         package E; @ISA = qw(C D);
 213         sub foo { print &quot;called E::foo\n&quot;; shift-&gt;NEXT::DISTINCT::foo() }</pre>
 214 <pre>
 215         E-&gt;foo();</pre>
 216 <p>then it would print:
 217 </p>
 218 <pre>
 219
 220         called E::foo
 221         called C::foo
 222         called A::foo
 223         called D::foo
 224         called B::foo</pre>
 225 <p>and omit the second call to <code>A::foo</code> (since it would not be distinct
 226 from the first call to <code>A::foo</code>).</p>
 227 <p>Note that you can also use:</p>
 228 <pre>
 229         $self-&gt;NEXT::DISTINCT::ACTUAL::method();</pre>
 230 <p>or:</p>
 231 <pre>
 232         $self-&gt;NEXT::ACTUAL::DISTINCT::method();</pre>
 233 <p>to get both unique invocation <em>and</em> exception-on-failure.</p>
 234 <p>Note that, for historical compatibility, you can also use
 235 <code>NEXT::UNSEEN</code> instead of <code>NEXT::DISTINCT</code>.</p>
 236 <p>
 237 </p>
 238 <h2><a name="invoking_all_versions_of_a_method_with_a_single_call">Invoking all versions of a method with a single call</a></h2>
 239 <p>Yet another pseudo-class that NEXT.pm provides is <code>EVERY</code>.
 240 Its behaviour is considerably simpler than that of the <code>NEXT</code> family.
 241 A call to:</p>
 242 <pre>
 243         $obj-&gt;EVERY::foo();</pre>
 244 <p>calls <em>every</em> method named <code>foo</code> that the object in <code>$obj</code> has inherited.
 245 That is:</p>
 246 <pre>
 247         use NEXT;</pre>
 248 <pre>
 249         package A; @ISA = qw(B D X);
 250         sub foo { print &quot;A::foo &quot; }</pre>
 251 <pre>
 252         package B; @ISA = qw(D X);
 253         sub foo { print &quot;B::foo &quot; }</pre>
 254 <pre>
 255         package X; @ISA = qw(D);
 256         sub foo { print &quot;X::foo &quot; }</pre>
 257 <pre>
 258         package D;
 259         sub foo { print &quot;D::foo &quot; }</pre>
 260 <pre>
 261         package main;</pre>
 262 <pre>
 263         my $obj = bless {}, 'A';
 264         $obj-&gt;EVERY::foo();        # prints&quot; A::foo B::foo X::foo D::foo</pre>
 265 <p>Prefixing a method call with <code>EVERY::</code> causes every method in the
 266 object's hierarchy with that name to be invoked. As the above example
 267 illustrates, they are not called in Perl's usual ``left-most-depth-first''
 268 order. Instead, they are called ``breadth-first-dependency-wise''.</p>
 269 <p>That means that the inheritance tree of the object is traversed breadth-first
 270 and the resulting order of classes is used as the sequence in which methods
 271 are called. However, that sequence is modified by imposing a rule that the
 272 appropritae method of a derived class must be called before the same method of
 273 any ancestral class. That's why, in the above example, <code>X::foo</code> is called
 274 before <code>D::foo</code>, even though <code>D</code> comes before <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_x"><code>X</code></a> in <code>@B::ISA</code>.</p>
 275 <p>In general, there's no need to worry about the order of calls. They will be
 276 left-to-right, breadth-first, most-derived-first. This works perfectly for
 277 most inherited methods (including destructors), but is inappropriate for
 278 some kinds of methods (such as constructors, cloners, debuggers, and
 279 initializers) where it's more appropriate that the least-derived methods be
 280 called first (as more-derived methods may rely on the behaviour of their
 281 ``ancestors''). In that case, instead of using the <code>EVERY</code> pseudo-class:</p>
 282 <pre>
 283         $obj-&gt;EVERY::foo();        # prints&quot; A::foo B::foo X::foo D::foo</pre>
 284 <p>you can use the <code>EVERY::LAST</code> pseudo-class:</p>
 285 <pre>
 286         $obj-&gt;EVERY::LAST::foo();  # prints&quot; D::foo X::foo B::foo A::foo</pre>
 287 <p>which reverses the order of method call.</p>
 288 <p>Whichever version is used, the actual methods are called in the same
 289 context (list, scalar, or void) as the original call via <code>EVERY</code>, and return:</p>
 290 <ul>
 291 <li>
 292 <p>A hash of array references in list context. Each entry of the hash has the
 293 fully qualified method name as its key and a reference to an array containing
 294 the method's list-context return values as its value.</p>
 295 </li>
 296 <li>
 297 <p>A reference to a hash of scalar values in scalar context. Each entry of the hash has the
 298 fully qualified method name as its key and the method's scalar-context return values as its value.</p>
 299 </li>
 300 <li>
 301 <p>Nothing in void context (obviously).</p>
 302 </li>
 303 </ul>
 304 <p>
 305 </p>
 306 <h2><a name="using_every_methods">Using <code>EVERY</code> methods</a></h2>
 307 <p>The typical way to use an <code>EVERY</code> call is to wrap it in another base
 308 method, that all classes inherit. For example, to ensure that every
 309 destructor an object inherits is actually called (as opposed to just the
 310 left-most-depth-first-est one):</p>
 311 <pre>
 312         package Base;
 313         sub DESTROY { $_[0]-&gt;EVERY::Destroy }</pre>
 314 <pre>
 315         package Derived1;
 316         use base 'Base';
 317         sub Destroy {...}</pre>
 318 <pre>
 319         package Derived2;
 320         use base 'Base', 'Derived1';
 321         sub Destroy {...}</pre>
 322 <p>et cetera. Every derived class than needs its own clean-up
 323 behaviour simply adds its own <code>Destroy</code> method (<em>not</em> a <code>DESTROY</code> method),
 324 which the call to <code>EVERY::LAST::Destroy</code> in the inherited destructor
 325 then correctly picks up.</p>
 326 <p>Likewise, to create a class hierarchy in which every initializer inherited by
 327 a new object is invoked:</p>
 328 <pre>
 329         package Base;
 330         sub new {
 331                 my ($class, %args) = @_;
 332                 my $obj = bless {}, $class;
 333                 $obj-&gt;EVERY::LAST::Init(\%args);
 334         }</pre>
 335 <pre>
 336         package Derived1;
 337         use base 'Base';
 338         sub Init {
 339                 my ($argsref) = @_;
 340                 ...
 341         }</pre>
 342 <pre>
 343         package Derived2;
 344         use base 'Base', 'Derived1';
 345         sub Init {
 346                 my ($argsref) = @_;
 347                 ...
 348         }</pre>
 349 <p>et cetera. Every derived class than needs some additional initialization
 350 behaviour simply adds its own <code>Init</code> method (<em>not</em> a <code>new</code> method),
 351 which the call to <code>EVERY::LAST::Init</code> in the inherited constructor
 352 then correctly picks up.</p>
 353 <p>
 354 </p>
 355 <hr />
 356 <h1><a name="author">AUTHOR</a></h1>
 357 <p>Damian Conway (<a href="mailto:damian@conway.org">damian@conway.org</a>)</p>
 358 <p>
 359 </p>
 360 <hr />
 361 <h1><a name="bugs_and_irritations">BUGS AND IRRITATIONS</a></h1>
 362 <p>Because it's a module, not an integral part of the interpreter, NEXT.pm
 363 has to guess where the surrounding call was found in the method
 364 look-up sequence. In the presence of diamond inheritance patterns
 365 it occasionally guesses wrong.</p>
 366 <p>It's also too slow (despite caching).</p>
 367 <p>Comment, suggestions, and patches welcome.</p>
 368 <p>
 369 </p>
 370 <hr />
 371 <h1><a name="copyright">COPYRIGHT</a></h1>
 372 <pre>
 373  Copyright (c) 2000-2001, Damian Conway. All Rights Reserved.
 374  This module is free software. It may be used, redistributed
 375     and/or modified under the same terms as Perl itself.
 376 </pre>
 377 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 378 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 379 <big><strong><span class="block">&nbsp;NEXT.pm - Provide a pseudo-class NEXT that allows method redispatch</span></strong></big>
 380 </td></tr>
 381 </table>
 382
 383 </body>
 384
 385 </html>