1NEXT(3pm) Perl Programmers Reference Guide NEXT(3pm)
2
6 NEXT - Provide a pseudo-class NEXT (et al) that allows method
7 redispatch
8
10 use NEXT;
11 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 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 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 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 package main;
33 my $obj = bless {}, "S";
35 $obj->method(); # Calls S::method, P::method, R::method
37 $obj->missing_method(); # Calls S::AUTOLOAD, Q::AUTOLOAD, R::AUTOLOAD
38 # 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 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 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 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 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 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 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 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 sub S::oops { print "oops!\n"; $_[0]->NEXT::other_method() }
83 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 To do this, simple invoke the redispatch as:
90 $self->NEXT::ACTUAL::method();
92 rather than:
94 $self->NEXT::method();
96 The "ACTUAL" tells "NEXT" that there must actually be a next method to
98 call, or it should throw an exception.
99 "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 sub AUTOLOAD {
105 if ($AUTOLOAD =~ /foo|bar/) {
106 # handle here
107 }
108 else { # try elsewhere
109 shift()->NEXT::ACTUAL::AUTOLOAD(@_);
110 }
111 }
112 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 Avoiding repetitions
118 If "NEXT" redispatching is used in the methods of a "diamond" class
119 hierarchy:
120 # A B
122 # / \ /
123 # C D
124 # \ /
125 # E
126 use NEXT;
128 package A;
130 sub foo { print "called A::foo\n"; shift->NEXT::foo() }
131 package B;
133 sub foo { print "called B::foo\n"; shift->NEXT::foo() }
134 package C; @ISA = qw( A );
136 sub foo { print "called C::foo\n"; shift->NEXT::foo() }
137 package D; @ISA = qw(A B);
139 sub foo { print "called D::foo\n"; shift->NEXT::foo() }
140 package E; @ISA = qw(C D);
142 sub foo { print "called E::foo\n"; shift->NEXT::foo() }
143 E->foo();
145 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 called E::foo
153 called C::foo
154 called A::foo
155 called D::foo
156 called A::foo
157 called B::foo
158 (i.e. "A::foo" is called twice).
160 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 To cover such cases, you can redispatch methods via:
167 $self->NEXT::DISTINCT::method();
169 rather than:
171 $self->NEXT::method();
173 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 package A;
180 sub foo { print "called A::foo\n"; shift->NEXT::DISTINCT::foo() }
181 package B;
183 sub foo { print "called B::foo\n"; shift->NEXT::DISTINCT::foo() }
184 package C; @ISA = qw( A );
186 sub foo { print "called C::foo\n"; shift->NEXT::DISTINCT::foo() }
187 package D; @ISA = qw(A B);
189 sub foo { print "called D::foo\n"; shift->NEXT::DISTINCT::foo() }
190 package E; @ISA = qw(C D);
192 sub foo { print "called E::foo\n"; shift->NEXT::DISTINCT::foo() }
193 E->foo();
195 then it would print:
197 called E::foo
199 called C::foo
200 called A::foo
201 called D::foo
202 called B::foo
203 and omit the second call to "A::foo" (since it would not be distinct
205 from the first call to "A::foo").
206 Note that you can also use:
208 $self->NEXT::DISTINCT::ACTUAL::method();
210 or:
212 $self->NEXT::ACTUAL::DISTINCT::method();
214 to get both unique invocation and exception-on-failure.
216 Note that, for historical compatibility, you can also use
218 "NEXT::UNSEEN" instead of "NEXT::DISTINCT".
219 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 $obj->EVERY::foo();
226 calls every method named "foo" that the object in $obj has inherited.
228 That is:
229 use NEXT;
231 package A; @ISA = qw(B D X);
233 sub foo { print "A::foo " }
234 package B; @ISA = qw(D X);
236 sub foo { print "B::foo " }
237 package X; @ISA = qw(D);
239 sub foo { print "X::foo " }
240 package D;
242 sub foo { print "D::foo " }
243 package main;
245 my $obj = bless {}, 'A';
247 $obj->EVERY::foo(); # prints" A::foo B::foo X::foo D::foo
248 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 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 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 $obj->EVERY::foo(); # prints" A::foo B::foo X::foo D::foo
272 you can use the "EVERY::LAST" pseudo-class:
274 $obj->EVERY::LAST::foo(); # prints" D::foo X::foo B::foo A::foo
276 which reverses the order of method call.
278 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 • 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 • 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 • Nothing in void context (obviously).
293 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 package Base;
301 sub DESTROY { $_[0]->EVERY::Destroy }
302 package Derived1;
304 use base 'Base';
305 sub Destroy {...}
306 package Derived2;
308 use base 'Base', 'Derived1';
309 sub Destroy {...}
310 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 Likewise, to create a class hierarchy in which every initializer
317 inherited by a new object is invoked:
318 package Base;
320 sub new {
321 my ($class, %args) = @_;
322 my $obj = bless {}, $class;
323 $obj->EVERY::LAST::Init(\%args);
324 }
325 package Derived1;
327 use base 'Base';
328 sub Init {
329 my ($argsref) = @_;
330 ...
331 }
332 package Derived2;
334 use base 'Base', 'Derived1';
335 sub Init {
336 my ($argsref) = @_;
337 ...
338 }
339 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 It's also too slow (despite caching).
360 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.
367perl v5.36.0 2022-08-30 NEXT(3pm)