Class::Delegator(3pm)

💖 Class::Delegator 💖

okay bestie, so this is Class::Delegator, from the User Contributed Perl Documentation corner of the perlverse, and it's literally just Simple and fast object-oriented delegation. that's the whole vibe. periodt.

---

✨ NAME ✨

Class::Delegator — Simple and fast object-oriented delegation 🦋

---

💅 SYNOPSIS 💅

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)]
;

look at her. gorgeous. no notes. 🎀

---

🌸 DESCRIPTION 🌸

so this module gives you a subset of what Damian Conway's lovely Class::Delegation does. why only a subset, bestie? well:

• she didn't need all the fancy matching semantics, just string string specifications to map delegations
• she wanted it to be fast (see the Benchmarks section, it's giving receipts 💀)
• 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

okay but heads up: the specification semantics of Class::Delegator differ slightly from those of Class::Delegation, so this module is not a drop-in replacement for Class::Delegation. Read on for details, bestie. 🙈

🧚 Specifying methods to be delegated

the names of methods to be redispatched get specified with the "send" parameter. she can be a single string or an array of strings. a single string = a single method to be delegated; an array reference = a whole list of methods to be delegated. slay. ✨

👑 Specifying attributes to be delegated to

use the "to" parameter to say which attribute(s) or accessor method(s) the method(s) from "send" get delegated to.

the semantics of the "to" parameter are a bit different from Class::Delegation ngl. to guarantee the fastest possible performance, this module just installs methods into the calling class to handle the delegation. no $AUTOLOAD, no trickery, none of it. but since those new methods get installed by "eval"ing a string, the "to" parameter for each delegation statement has to be written in the manner appropriate to accessing the underlying attribute. fyi.

so, to delegate a method call to an attribute stored in a hash key, just wrap the key in braces:

use Class::Delegator
    send => 'start',
      to => '{engine}',
;

to delegate to a method, just 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. 💜

🎀 Specifying the name of a delegated method

sometimes the method being delegated needs a different name from the method you're delegating to. like, your class might already have a method with the same name as the method you're delegating to. awkward. 😭 the "as" parameter lets 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). keep those counts matching, bestie, i'm begging.

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. iconic pairing tbh. 🫶

🌈 Delegation to multiple attributes in parallel

an array reference can be used as the value of the "to" parameter to specify 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. not optional, bestie.

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(...);

---

🔥 BENCHMARKS 🔥

she whipped up a quick script to compare the performance of Class::Delegator vs Class::Delegation vs a manually-installed delegation method (the control). and honestly? the numbers speak for themselves, so she's just gonna let them. 💀

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)

ate and left no crumbs. the control is literally right there and she's basically keeping up. 👑

---

💀 BUGS 💀

please send bug reports to <bug-class-delegator@rt.cpan.org> or report them via the CPAN Request Tracker at <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Class-Delegator>.

she's not mad, she just wants to know. 😭

---

🌟 AUTHOR 🌟

David Wheeler <david@kineticode.com>

---

🦋 SEE ALSO 🦋

• Class::Delegation — Damian Conway's brilliant module does ten times what this one does--and does it ten times slower. (not me being shady, that's literally the text. 😭 iconic though.)
• 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. (we have "as". we win. 💅)

---

🎀 COPYRIGHT AND LICENSE 🎀

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.

---

okay that's the whole page bestie, no cap, every last flag and detail intact 💖 mwah! and for the little receipt at the bottom: this was perl v5.36.0, dated 2022-10-13 — thanks for reading Class::Delegator(3pm), love u, bye! 🦋✨💅