3 package Catalyst::Plugin::Cache;
4 use base qw(Class::Accessor::Fast Class::Data::Inheritable);
12 use Catalyst::Utils ();
16 use Catalyst::Plugin::Cache::Curried;
18 __PACKAGE__->mk_classdata( "_cache_backends" );
19 __PACKAGE__->mk_accessors( "_default_curried_cache" );
24 # set it once per app, not once per plugin,
25 # and don't overwrite if some plugin was wicked
26 $app->_cache_backends({}) unless $app->_cache_backends;
28 my $ret = $app->NEXT::setup( @_ );
30 $app->setup_cache_backends;
35 sub get_default_cache_backend_config {
36 my ( $app, $name ) = @_;
37 $app->config->{cache}{backend} || $app->get_cache_backend_config("default");
40 sub get_cache_backend_config {
41 my ( $app, $name ) = @_;
42 $app->config->{cache}{backends}{$name};
45 sub setup_cache_backends {
48 # give plugins a chance to find things for themselves
49 $app->NEXT::setup_cache_backends;
51 foreach my $name ( keys %{ $app->config->{cache}{backends} } ) {
52 next if $app->get_cache_backend( $name );
53 $app->setup_generic_cache_backend( $name, $app->get_cache_backend_config( $name ) || {} );
56 if ( !$app->get_cache_backend("default") ) {
57 ### XXX currently we dont have a fallback scenario
58 ### so die here with the error message. Once we have
59 ### an in memory fallback, we may consider silently
60 ### logging the error and falling back to that.
61 ### If we dont die here, the app will silently start
62 ### up and then explode at the first cache->get or
63 ### cache->set request with a FIXME error
66 $app->setup_generic_cache_backend( default => $app->get_default_cache_backend_config || {} );
72 sub default_cache_store {
74 $app->config->{cache}{default_store} || $app->guess_default_cache_store;
77 sub guess_default_cache_store {
80 my @stores = map { /Cache::Store::(.*)$/ ? $1 : () } $app->registered_plugins;
85 Carp::croak "You must configure a default store type unless you use exactly one store plugin.";
89 sub setup_generic_cache_backend {
90 my ( $app, $name, $config ) = @_;
91 my %config = %$config;
93 if ( my $class = delete $config{class} ) {
95 ### try as list and as hashref, collect the
96 ### error if things go wrong
97 ### if all goes well, exit the loop
99 for my $aref ( [%config], [\%config] ) {
100 eval { $app->setup_cache_backend_by_class(
101 $name, $class, @$aref
103 } ? do { @errors = (); last }
104 : push @errors, "\t$@";
107 ### and die with the errors if we have any
108 die "Couldn't construct $class with either list style or hash ref style param passing:\n @errors" if @errors;
110 } elsif ( my $store = delete $config->{store} || $app->default_cache_store ) {
111 my $method = lc("setup_${store}_cache_backend");
113 Carp::croak "You must load the $store cache store plugin (if it exists). ".
114 "Please consult the Catalyst::Plugin::Cache documentation on how to configure hetrogeneous stores."
115 unless $app->can($method);
117 $app->$method( $name, \%config );
119 $app->log->warn("Couldn't setup the cache backend named '$name'");
123 sub setup_cache_backend_by_class {
124 my ( $app, $name, $class, @args ) = @_;
125 Catalyst::Utils::ensure_class_loaded( $class );
126 $app->register_cache_backend( $name => $class->new( @args ) );
129 # end of spaghetti setup DWIM
132 my ( $c, @meta ) = @_;
136 return ( $c->get_preset_curried($name) || $c->get_cache_backend($name) );
138 # be nice and always return the same one for the simplest case
139 return ( $c->_default_curried_cache || $c->_default_curried_cache( $c->curry_cache( @meta ) ) );
141 return $c->curry_cache( @meta );
145 sub construct_curried_cache {
146 my ( $c, @meta ) = @_;
147 return $c->curried_cache_class( @meta )->new( @meta );
150 sub curried_cache_class {
151 my ( $c, @meta ) = @_;
152 $c->config->{cache}{curried_class} || "Catalyst::Plugin::Cache::Curried";
156 my ( $c, @meta ) = @_;
157 return $c->construct_curried_cache( $c, $c->_cache_caller_meta, @meta );
160 sub get_preset_curried {
161 my ( $c, $name ) = @_;
163 if ( ref( my $preset = $c->config->{cache}{profiles}{$name} ) ) {
164 return $preset if Scalar::Util::blessed($preset);
166 my @meta = ( ( ref $preset eq "HASH" ) ? %$preset : @$preset );
167 return $c->curry_cache( @meta );
173 sub get_cache_backend {
174 my ( $c, $name ) = @_;
175 $c->_cache_backends->{$name};
178 sub register_cache_backend {
179 my ( $c, $name, $backend ) = @_;
181 no warnings 'uninitialized';
182 Carp::croak("$backend does not look like a cache backend - "
183 . "it must be an object supporting get, set and remove")
184 unless eval { $backend->can("get") && $backend->can("set") && $backend->can("remove") };
186 $c->_cache_backends->{$name} = $backend;
189 sub unregister_cache_backend {
190 my ( $c, $name ) = @_;
191 delete $c->_cache_backends->{$name};
194 sub default_cache_backend {
196 $c->get_cache_backend( "default" ) || $c->temporary_cache_backend;
199 sub temporary_cache_backend {
201 die "FIXME - make up an in memory cache backend, that hopefully works well for the current engine";
204 sub _cache_caller_meta {
207 my ( $caller, $component, $controller );
209 for my $i ( 0 .. 15 ) { # don't look to far
210 my @info = caller(2 + $i) or last;
212 $caller ||= \@info unless $info[0] =~ /Plugin::Cache/;
213 $component ||= \@info if $info[0]->isa("Catalyst::Component");
214 $controller ||= \@info if $info[0]->isa("Catalyst::Controller");
216 last if $caller && $component && $controller;
219 my ( $caller_pkg, $component_pkg, $controller_pkg ) =
220 map { $_ ? $_->[0] : undef } $caller, $component, $controller;
223 'caller' => $caller_pkg,
224 component => $component_pkg,
225 controller => $controller_pkg,
226 caller_frame => $caller,
227 component_frame => $component,
228 controller_frame => $controller,
232 # this gets a shit name so that the plugins can override a good name
233 sub choose_cache_backend_wrapper {
234 my ( $c, @meta ) = @_;
236 Carp::croak("metadata must be an even sized list") unless @meta % 2 == 0;
240 unless ( exists $meta{'caller'} ) {
241 my %caller = $c->_cache_caller_meta;
242 @meta{keys %caller} = values %caller;
245 # allow the cache client to specify who it wants to cache with (but loeave room for a hook)
246 if ( exists $meta{backend} ) {
247 if ( Scalar::Util::blessed($meta{backend}) ) {
248 return $meta{backend};
250 return $c->get_cache_backend( $meta{backend} ) || $c->default_cache_backend;
254 if ( my $chosen = $c->choose_cache_backend( %meta ) ) {
255 $chosen = $c->get_cache_backend( $chosen ) unless Scalar::Util::blessed($chosen); # if it's a name find it
256 return $chosen if Scalar::Util::blessed($chosen); # only return if it was an object or name lookup worked
259 # die "no such backend"?
260 # currently, we fall back to default
263 return $c->default_cache_backend;
266 sub choose_cache_backend { shift->NEXT::choose_cache_backend( @_ ) } # a convenient fallback
269 my ( $c, $key, $value, %meta ) = @_;
270 $c->choose_cache_backend_wrapper( key => $key, value => $value, %meta )
271 ->set( $key, $value, exists $meta{expires} ? $meta{expires} : () );
275 my ( $c, $key, @meta ) = @_;
276 $c->choose_cache_backend_wrapper( key => $key, @meta )->get( $key );
280 my ( $c, $key, @meta ) = @_;
281 $c->choose_cache_backend_wrapper( key => $key, @meta )->remove( $key );
292 Catalyst::Plugin::Cache - Flexible caching support for Catalyst.
300 # configure a backend or use a store plugin
301 __PACKAGE__->config->{cache}{backend} = {
302 class => "Cache::Bounded",
303 # ... params for Cache::Bounded...
306 # typical example for Cache::Memcached::libmemcached
307 __PACKAGE__->config->{cache}{backend} = {
308 class => "Cache::Memcached::libmemcached",
309 servers => ['127.0.0.1:11211'],
317 my ( $self, $c, $id ) = @_;
319 my $cache = $c->cache;
323 unless ( $result = $cache->get( $id ) ) {
324 # ... calculate result ...
325 $c->cache->set( $id, $result );
331 This plugin gives you access to a variety of systems for caching
332 data. It allows you to use a very simple configuration API, while
333 maintaining the possibility of flexibility when you need it later.
335 Among its features are support for multiple backends, segmentation based
336 on component or controller, keyspace partitioning, and so more, in
337 various subsidiary plugins.
343 =item cache $profile_name
347 Return a curried object with metadata from C<$profile_name> or as
348 explicitly specified.
350 If a profile by the name C<$profile_name> doesn't exist, but a backend
351 object by that name does exist, the backend will be returned instead,
352 since the interface for curried caches and backends is almost identical.
354 This method can also be called without arguments, in which case is
355 treated as though the C<%meta> hash was empty.
357 See L</METADATA> for details.
359 =item curry_cache %meta
361 Return a L<Catalyst::Plugin::Cache::Curried> object, curried with C<%meta>.
363 See L</METADATA> for details.
365 =item cache_set $key, $value, %meta
367 =item cache_get $key, %meta
369 =item cache_remove $key, %meta
371 These cache operations will call L<choose_cache_backend> with %meta, and
372 then call C<set>, C<get>, or C<remove> on the resulting backend object.
374 =item choose_cache_backend %meta
376 Select a backend object. This should return undef if no specific backend
377 was selected - its caller will handle getting C<default_cache_backend>
380 This method is typically used by plugins.
382 =item get_cache_backend $name
384 Get a backend object by name.
386 =item default_cache_backend
388 Return the default backend object.
390 =item temporary_cache_backend
392 When no default cache backend is configured this method might return a
393 backend known to work well with the current L<Catalyst::Engine>. This is
404 Whenever you set or retrieve a key you may specify additional metadata
405 that will be used to select a specific backend.
407 This metadata is very freeform, and the only key that has any meaning by
408 default is the C<backend> key which can be used to explicitly choose a backend
411 The C<choose_cache_backend> method can be overridden in order to
412 facilitate more intelligent backend selection. For example,
413 L<Catalyst::Plugin::Cache::Choose::KeyRegexes> overrides that method to
414 select a backend based on key regexes.
416 Another example is a L<Catalyst::Plugin::Cache::ControllerNamespacing>,
417 which wraps backends in objects that perform key mangling, in order to
418 keep caches namespaced per controller.
420 However, this is generally left as a hook for larger, more complex
421 applications. Most configurations should make due XXXX
423 The simplest way to dynamically select a backend is based on the
424 L</Cache Profiles> configuration.
426 =head2 Meta Data Keys
428 C<choose_cache_backend> is called with some default keys.
434 Supplied by C<cache_get>, C<cache_set>, and C<cache_remove>.
438 Supplied by C<cache_set>.
442 The package name of the innermost caller that doesn't match
443 C<qr/Plugin::Cache/>.
447 The entire C<caller($i)> frame of C<caller>.
451 The package name of the innermost caller who C<isa>
452 L<Catalyst::Component>.
454 =item component_frame
456 This entire C<caller($i)> frame of C<component>.
460 The package name of the innermost caller who C<isa>
461 L<Catalyst::Controller>.
463 =item controller_frame
465 This entire C<caller($i)> frame of C<controller>.
469 =head2 Metadata Currying
471 In order to avoid specifying C<%meta> over and over again you may call
472 C<cache> or C<curry_cache> with C<%meta> once, and get back a B<curried
473 cache object>. This object responds to the methods C<get>, C<set>, and
474 C<remove>, by appending its captured metadata and delegating them to
475 C<cache_get>, C<cache_set>, and C<cache_remove>.
477 This is simpler than it sounds.
479 Here is an example using currying:
481 my $cache = $c->cache( %meta ); # cache is curried
483 $cache->set( $key, $value );
487 And here is an example without using currying:
489 $c->cache_set( $key, $value, %meta );
491 $c->cache_get( $key, %meta );
493 See L<Catalyst::Plugin::Cache::Curried> for details.
497 $c->config->{cache} = {
501 All configuration parameters should be provided in a hash reference
502 under the C<cache> key in the C<config> hash.
504 =head2 Backend Configuration
506 Configuring backend objects is done by adding hash entries under the
507 C<backends> key in the main config.
509 A special case is that the hash key under the C<backend> (singular) key
510 of the main config is assumed to be the backend named C<default>.
516 Instantiate a backend from a L<Cache> compatible class. E.g.
518 $c->config->{cache}{backends}{small_things} = {
519 class => "Cache::Bounded",
524 $c->config->{cache}{backends}{large_things} = {
525 class => "Cache::Memcached",
526 data => '1.2.3.4:1234',
529 The options in the hash are passed to the class's C<new> method.
531 The class will be C<required> as necessary during setup time.
535 Instantiate a backend using a store plugin, e.g.
537 $c->config->{cache}{backend} = {
541 Store plugins typically require less configuration because they are
542 specialized for L<Catalyst> applications. For example
543 L<Catalyst::Plugin::Cache::Store::FastMmap> will specify a default
544 C<share_file>, and additionally use a subclass of L<Cache::FastMmap>
545 that can also store non reference data.
547 The store plugin must be loaded.
551 =head2 Cache Profiles
557 Supply your own predefined profiles for cache metadata, when using the
560 For example when you specify
562 $c->config->{cache}{profiles}{thumbnails} = {
563 backend => "large_things",
566 And then get a cache object like this:
568 $c->cache("thumbnails");
570 It is the same as if you had done:
572 $c->cache( backend => "large_things" );
576 =head2 Miscellaneous Configuration
582 When you do not specify a C<store> parameter in the backend
583 configuration this one will be used instead. This configuration
584 parameter is not necessary if only one store plugin is loaded.
594 An object that responds to the methods detailed in
595 L<Catalyst::Plugin::Cache::Backend> (or more).
599 A plugin that provides backends of a certain type. This is a bit like a
604 Stored key/value pairs of data for easy re-access.
608 "Extra" information about the item being stored, which can be used to
609 locate an appropriate backend.
613 my $cache = $c->cache(type => 'thumbnails');
614 $cache->set('pic01', $thumbnaildata);
616 A cache which has been pre-configured with a particular set of
617 namespacing data. In the example the cache returned could be one
618 specifically tuned for storing thumbnails.
620 An object that responds to C<get>, C<set>, and C<remove>, and will
621 automatically add metadata to calls to C<< $c->cache_get >>, etc.
627 L<Cache> - the generic cache API on CPAN.
629 L<Catalyst::Plugin::Cache::Store> - how to write a store plugin.
631 L<Catalyst::Plugin::Cache::Curried> - the interface for curried caches.
633 L<Catalyst::Plugin::Cache::Choose::KeyRegexes> - choose a backend based on
634 regex matching on the keys. Can be used to partition the keyspace.
636 L<Catalyst::Plugin::Cache::ControllerNamespacing> - wrap backend objects in a
637 name mangler so that every controller gets its own keyspace.
641 Yuval Kogman, C<nothingmuch@woobling.org>
643 =head1 COPYRIGHT & LICENSE
645 Copyright (c) Yuval Kogman, 2006. All rights reserved.
647 This library is free software, you can redistribute it and/or modify it under
648 the same terms as Perl itself, as well as under the terms of the MIT license.