[gitmo/MooseX-Attribute-Cached.git] / lib / MooseX / Attribute / Cached.pm

package MooseX::Attribute::Cached;

use Moose;


=head1 NAME

MooseX::Attribute::Cached; Cache your Moose Attribute Value

=head2 AUTHORITY

cpan:JJNAPIORK

=cut

our $AUTHORITY = 'cpan:JJNAPIORK';

=head1 VERSION

Version 0.01

=cut

our $VERSION = '0.01';

=head1 SYNOPSIS

	package MyApp;
	
	use Moose;
	with 'MooseX::Attribute::Cached';

	## Cache Storage Options Declared Manually
	has 'shared_key_1' => (
		traits => ['Cached'],
		cache_storage => ['Memcached' => {
			'servers' => [ "10.0.0.15:11211", "10.0.0.15:11212"],
		}], 
		%other_attribute_options_1,
	);
	
	## This attribute get's it's cache storage from a method, which can be
	## called from a lazy attribute or as a package method
	has 'shared_key_2' => (
		traits => ['Cached'],
		storage_key=>'something_different_shared_key_2',
		%other_attribute_options_2,
	);
	
	## Here's the provider for the attributes storage.  Basically you need to
	## return the storage provider name and it's instantiation args.
	sub _cache_storage_options_shared_key_2 {
		## If the calling attribute is lazy get's $self, otherwise we
		## gets __PACKAGE__.  Getting $self could be useful if you are reading
		## the cache options from something like your config object, etc.
		my $self = shift @_;
		return [
			'Memcached' => {
				'servers' => [
					"10.0.0.15:11211", 
					"10.0.0.15:11212", 
					"/var/sock/memcached",
					"10.0.0.17:11211",
					[ "10.0.0.17:11211", 3 ],
				],
				'debug' => 0,
				'compress_threshold' => 10_000,
			},
		];
	}
	
	## <Rest of your Class Definition>
	
	1;

=head1 DESCRIPTION

Store the value of your Moose Attributes in a cached storage.  The purpose of 
this is to faciliate sharing of attribute values over various processes or 
every across machines, presuming you are using a distributed cache, 
like Memcached.  All instances with access to the same cache will share and 
update a common value.  That way:

1) All instances share the same attribute value.  Updates made by one 
attribute are seen by all instances, even on different servers as long as
they share a distributed caching system (such as Memcached).  

2) It can be a sort of 'persistance lite' although I highly recommend using
a real persistance system, such as a database or L<MooseX::Storage>.

3) You could probably use this as a sort of expensive class attribute, but
you will likely be more happy with L<MooseX::ClassAttribute>

Please keep in mind that the process of setting and getting values in and out
of the Cache is asynchronise.  When a value is updated, this is no 'Publish /
Subscribe' system running to let all the instances using this attribute know it
ha been changed.  Also, since the last value that was retrieved from the Cache
is stored by the instance, any references will point to this.

At this time, this supports two Cachings systems, Memcached and FastMmap.  If
you have need for other cache types, adding a driver for it should be easy, so
please send your patches and test cases.

=head1 AUTHOR

John Napiorkowski, C<< <john.napiorkowski at takkle.com> >>

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc MooseX::Attributes::Cached

You can also look for information at:

=over 4

=item * RT: CPAN's request tracker

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=MooseX-Attributes-Cached>

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/MooseX-Attributes-Cached>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/MooseX-Attributes-Cached>

=item * Search CPAN

L<http://search.cpan.org/dist/MooseX-Attributes-CachedF>

=back

=head1 SEE ALSO

L<Moose>, L<MooseX::ClassAttribute>, L<MooseX::Storage>, L<Cache::FastMmap>,
L<Cache::Memcached>

=head1 COPYRIGHT & LICENSE

Copyright 2008 John Napiorkowski

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

=cut

no Moose; 1; # End of MooseX::Attributes::Cached
Commit	Line	Data
cf0ef7c5	1	package MooseX::Attribute::Cached;
	2
	3	use Moose;
	4
d0e2ab77	5
cf0ef7c5	6	=head1 NAME
	7
	8	MooseX::Attribute::Cached; Cache your Moose Attribute Value
	9
	10	=head2 AUTHORITY
	11
	12	cpan:JJNAPIORK
	13
	14	=cut
	15
	16	our $AUTHORITY = 'cpan:JJNAPIORK';
	17
	18	=head1 VERSION
	19
	20	Version 0.01
	21
	22	=cut
	23
	24	our $VERSION = '0.01';
	25
	26	=head1 SYNOPSIS
	27
	28	package MyApp;
	29
	30	use Moose;
d0e2ab77	31	with 'MooseX::Attribute::Cached';
cf0ef7c5	32
	33	## Cache Storage Options Declared Manually
	34	has 'shared_key_1' => (
	35	traits => ['Cached'],
	36	cache_storage => ['Memcached' => {
	37	'servers' => [ "10.0.0.15:11211", "10.0.0.15:11212"],
	38	}],
	39	%other_attribute_options_1,
	40	);
	41
	42	## This attribute get's it's cache storage from a method, which can be
	43	## called from a lazy attribute or as a package method
	44	has 'shared_key_2' => (
	45	traits => ['Cached'],
	46	storage_key=>'something_different_shared_key_2',
	47	%other_attribute_options_2,
	48	);
	49
	50	## Here's the provider for the attributes storage. Basically you need to
	51	## return the storage provider name and it's instantiation args.
	52	sub _cache_storage_options_shared_key_2 {
	53	## If the calling attribute is lazy get's $self, otherwise we
	54	## gets __PACKAGE__. Getting $self could be useful if you are reading
	55	## the cache options from something like your config object, etc.
	56	my $self = shift @_;
	57	return [
	58	'Memcached' => {
	59	'servers' => [
	60	"10.0.0.15:11211",
	61	"10.0.0.15:11212",
	62	"/var/sock/memcached",
	63	"10.0.0.17:11211",
	64	[ "10.0.0.17:11211", 3 ],
	65	],
	66	'debug' => 0,
	67	'compress_threshold' => 10_000,
	68	},
	69	];
	70	}
	71
	72	## <Rest of your Class Definition>
	73
	74	1;
	75
	76	=head1 DESCRIPTION
	77
	78	Store the value of your Moose Attributes in a cached storage. The purpose of
	79	this is to faciliate sharing of attribute values over various processes or
	80	every across machines, presuming you are using a distributed cache,
	81	like Memcached. All instances with access to the same cache will share and
	82	update a common value. That way:
	83
d0e2ab77	84	1) All instances share the same attribute value. Updates made by one
cf0ef7c5	85	attribute are seen by all instances, even on different servers as long as
d0e2ab77	86	they share a distributed caching system (such as Memcached).
d0e2ab77	87
cf0ef7c5	88	2) It can be a sort of 'persistance lite' although I highly recommend using
cf0ef7c5	89	a real persistance system, such as a database or L<MooseX::Storage>.
d0e2ab77	90
cf0ef7c5	91	3) You could probably use this as a sort of expensive class attribute, but
	92	you will likely be more happy with L<MooseX::ClassAttribute>
	93
d0e2ab77	94	Please keep in mind that the process of setting and getting values in and out
	95	of the Cache is asynchronise. When a value is updated, this is no 'Publish /
	96	Subscribe' system running to let all the instances using this attribute know it
	97	ha been changed. Also, since the last value that was retrieved from the Cache
	98	is stored by the instance, any references will point to this.
	99
cf0ef7c5	100	At this time, this supports two Cachings systems, Memcached and FastMmap. If
	101	you have need for other cache types, adding a driver for it should be easy, so
	102	please send your patches and test cases.
	103
	104	=head1 AUTHOR
	105
	106	John Napiorkowski, C<< <john.napiorkowski at takkle.com> >>
	107
	108	=head1 SUPPORT
	109
	110	You can find documentation for this module with the perldoc command.
	111
	112	perldoc MooseX::Attributes::Cached
	113
	114	You can also look for information at:
	115
	116	=over 4
	117
	118	=item * RT: CPAN's request tracker
	119
	120	L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=MooseX-Attributes-Cached>
	121
	122	=item * AnnoCPAN: Annotated CPAN documentation
	123
	124	L<http://annocpan.org/dist/MooseX-Attributes-Cached>
	125
	126	=item * CPAN Ratings
	127
	128	L<http://cpanratings.perl.org/d/MooseX-Attributes-Cached>
	129
	130	=item * Search CPAN
	131
	132	L<http://search.cpan.org/dist/MooseX-Attributes-CachedF>
	133
	134	=back
	135
	136	=head1 SEE ALSO
	137
	138	L<Moose>, L<MooseX::ClassAttribute>, L<MooseX::Storage>, L<Cache::FastMmap>,
	139	L<Cache::Memcached>
	140
	141	=head1 COPYRIGHT & LICENSE
	142
d0e2ab77	143	Copyright 2008 John Napiorkowski
cf0ef7c5	144
	145	This program is free software; you can redistribute it and/or modify it
	146	under the same terms as Perl itself.
	147
	148	=cut
	149
	150	no Moose; 1; # End of MooseX::Attributes::Cached