Class::Delegator - Simple and fast object-oriented delegation
package Car;
use Class::Delegator
send => 'start',
to => '{engine}',
send => 'power',
to => 'flywheel',
as => 'brake',
send => [qw(play pause rewind fast_forward shuffle)],
to => 'ipod',
send => [qw(accelerate decelerate)],
to => 'brakes',
as => [qw(start stop)],
send => 'drive',
to => [qw(right_rear_wheel left_rear_wheel)],
as => [qw(rotate_clockwise rotate_anticlockwise)]
;
This module provides a subset of the functionality of Damian Conway's lovely
Class::Delegation module. Why a subset? Well, I didn't need all of the fancy
matching semantics, just string string specifications to map delegations.
Furthermore, I wanted it to be fast (See Benchmarks). And finally, since
Class::Delegation uses an "INIT" block to do its magic, it doesn't
work in persistent environments that don't execute "INIT" blocks,
such as in mod_perl.
However the specification semantics of Class::Delegator differ slightly from
those of Class::Delegation, so this module isn't a drop-in replacement for
Class::Delegation. Read on for details.
The names of methods to be redispatched can be specified using the
"send" parameter. This parameter may be specified as a single string
or as an array of strings. A single string specifies a single method to be
delegated, while an array reference is a list of methods to be delegated.
Use the "to" parameter to specify the attribute(s) or accessor
method(s) to which the method(s) specified by the "send" parameter
are to be delegated. The semantics of the "to" parameter are a bit
different from Class::Delegation. In order to ensure the fastest performance
possible, this module simply installs methods into the calling class to handle
the delegation. There is no use of $AUTOLOAD or other such trickery. But since
the new methods are installed by "eval"ing a string, the
"to" parameter for each delegation statement must be specified in
the manner appropriate to accessing the underlying attribute. For example, to
delegate a method call to an attribute stored in a hash key, simply wrap the
key in braces:
use Class::Delegator
send => 'start',
to => '{engine}',
;
To delegate to a method, simply name the method:
use Class::Delegator
send => 'power',
to => 'flywheel',
;
If your objects are array-based, wrap the appropriate array index number in
brackets:
use Class::Delegator
send => 'idle',
to => '[3]',
;
And so on.
Sometimes it's necessary for the name of the method that's being delegated to be
different from the name of the method to which you're delegating execution.
For example, your class might already have a method with the same name as the
method to which you're delegating. The "as" parameter allows you
translate the method name or names in a delegation statement. The value
associated with an "as" parameter specifies the name of the method
to be invoked, and may be a string or an array (with the number of elements in
the array matching the number of elements in a corresponding "send"
array).
If the attribute is specified via a single string, that string is taken as the
name of the attribute to which the associated method (or methods) should be
delegated. For example, to delegate invocations of
"$self->power(...)" to
"$self->{flywheel}->brake(...)":
use Class::Delegator
send => 'power',
to => '{flywheel}',
as => 'brake',
;
If both the "send" and the "as" parameters specify array
references, each local method name and deleted method name form a pair, which
is invoked. For example:
use Class::Delegator
send => [qw(accelerate decelerate)],
to => 'brakes',
as => [qw(start stop)],
;
In this example, the "accelerate" method will be delegated to the
"start" method of the "brakes" attribute and the
"decelerate" method will be delegated to the "stop" method
of the "brakes" attribute.
An array reference can be used as the value of the "to" parameter to
specify the a list of attributes,
all of which are delegated to--in the
same order as they appear in the array. In this case, the "send"
parameter
must be a scalar value, not an array of methods to delegate.
For example, to distribute invocations of "$self->drive(...)" to
both "$self->{left_rear_wheel}->drive(...)" and
"$self->{right_rear_wheel}->drive(...)":
use Class::Delegator
send => 'drive',
to => ["{left_rear_wheel}", "{right_rear_wheel}"]
;
Note that using an array to specify parallel delegation has an effect on the
return value of the delegation method specified by the "send"
parameter. In a scalar context, the original call returns a reference to an
array containing the (scalar context) return values of each of the calls. In a
list context, the original call returns a list of array references containing
references to the individual (list context) return lists of the calls. So, for
example, if the "cost" method of a class were delegated like so:
use Class::Delegator
send => 'cost',
to => ['supplier', 'manufacturer', 'distributor']
;
then the total cost could be calculated like this:
use List::Util 'sum';
my $total = sum @{$obj->cost()};
If both the "to" key and the "as" parameters specify
multiple values, then each attribute and method name form a pair, which is
invoked. For example:
use Class::Delegator
send => 'escape',
to => ['{flywheel}', '{smokescreen}'],
as => ['engage', 'release'],
;
would sequentially call, within the "escape()" delegation method:
$self->{flywheel}->engage(...);
$self->{smokescreen}->release(...);
I whipped up a quick script to compare the performance of Class::Delegator to
Class::Delegation and a manually-installed delegation method (the control).
I'll let the numbers speak for themselves:
Benchmark: timing 1000000 iterations of Class::Delegation, Class::Delegator, Manually...
Class::Delegation: 106 wallclock secs (89.03 usr + 2.09 sys = 91.12 CPU) @ 10974.54/s (n=1000000)
Class::Delegator: 3 wallclock secs ( 3.44 usr + 0.02 sys = 3.46 CPU) @ 289017.34/s (n=1000000)
Control: 3 wallclock secs ( 3.01 usr + 0.02 sys = 3.03 CPU) @ 330033.00/s (n=1000000)
Please send bug reports to <
[email protected]> or report
them via the CPAN Request Tracker at
<
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Class-Delegator>.
David Wheeler <
[email protected]>
- Class::Delegation
- Damian Conway's brilliant module does ten times what this
one does--and does it ten times slower.
- Class::Delegate
- Kurt Starsinic's module uses inheritance to manage
delegation, and has a somewhat more complex interface.
- Class::HasA
- Simon Cozen's delegation module takes the same approach as
this module, but provides no method for resolving method name clashes the
way this module's "as" parameter does.
Copyright (c) 2005-2008 David Wheeler. Some Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.