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