/ 
MooseX-Role-Flyweight-0.003
River stage one • 1 direct dependent • 1 total dependent
/ MooseX::Role::Flyweight

NAME

MooseX::Role::Flyweight - Automatically memoize and reuse your Moose objects

VERSION

version 0.003

SYNOPSIS

package MyClass;
use Moose;
with 'MooseX::Role::Flyweight';

package main;

my $unshared_object = MyClass->new(%args);
my $shared_object   = MyClass->instance(%args);
my $same_object     = MyClass->instance(%args);

DESCRIPTION

A million tiny objects can weigh a ton. They can also be expensive to construct. Instead of creating a multitude of identical copies of objects, a flyweight is a memoized instance that may be reused in multiple contexts simultaneously.

MooseX::Role::Flyweight enables your Moose class to automatically manage a cache of reusable instances. In other words, the class becomes its own flyweight factory.

WARNING! Your flyweight objects should be immutable. It is dangerous to have flyweight objects that can change state because it means you may get something you don't expect when you retrieve it from the cache the next time.

my $flight = Flight->instance(destination => 'Australia');
$flight->set_destination('Antarctica');

# later, in another context
my $flight = Flight->instance(destination => 'Australia');
die 'How did I end up in Antarctica?'
    if $flight->destination ne 'Australia';

METHODS

instance

my $obj = MyClass->instance(%constructor_args);

This class method retrieves the object from the cache for reuse, or constructs the object and stores it in the cache if it is not there already. The given arguments are those that are used by new() to construct the object. They are also used to identify the object in the cache.

The arguments may be in any form that new() will accept. This is normally a hash or hash reference of named parameters. Non-hash(ref) arguments are also possible if you have defined your own BUILDARGS class method to handle them (see Moose::Manual::Construction).

Note that this method will never return any object that has been constructed by directly calling new().

normalizer

my $obj_key = MyClass->normalizer(%constructor_args);

A class method that returns a string representation of the given arguments. This string representation is used by instance as the key to identify an object for storage and retrieval in the cache. Equivalent named parameters in a hash(ref) argument will always produce the same string because the hash keys will be sorted.

You may override this method with your own implementation.

AUTHOR

Steven Lee <stevenl@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Steven Lee.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.