[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;
	use 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 slot.  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>

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, all rights reserved.

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