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") ) {
58 eval { $app->setup_generic_cache_backend( default => $app->get_default_cache_backend_config || {} ) };
62 sub default_cache_store {
64 $app->config->{cache}{default_store} || $app->guess_default_cache_store;
67 sub guess_default_cache_store {
70 my @stores = map { /Cache::Store::(.*)$/ ? $1 : () } $app->registered_plugins;
75 Carp::croak "You must configure a default store type unless you use exactly one store plugin.";
79 sub setup_generic_cache_backend {
80 my ( $app, $name, $config ) = @_;
81 my %config = %$config;
83 if ( my $class = delete $config{class} ) {
84 eval { $app->setup_cache_backend_by_class( $name, $class, %config ) }
86 eval { $app->setup_cache_backend_by_class( $name, $class, \%config ) }
88 die "Couldn't construct $class with either list style or hash ref style param passing: $@";
89 } elsif ( my $store = delete $config->{store} || $app->default_cache_store ) {
90 my $method = lc("setup_${store}_cache_backend");
92 Carp::croak "You must load the $store cache store plugin (if it exists). ".
93 "Please consult the Catalyst::Plugin::Cache documentation on how to configure hetrogeneous stores."
94 unless $app->can($method);
96 $app->$method( $name, \%config );
98 $app->log->warn("Couldn't setup the cache backend named '$name'");
102 sub setup_cache_backend_by_class {
103 my ( $app, $name, $class, @args ) = @_;
104 Catalyst::Utils::ensure_class_loaded( $class );
105 $app->register_cache_backend( $name => $class->new( @args ) );
108 # end of spaghetti setup DWIM
111 my ( $c, @meta ) = @_;
115 return ( $c->get_preset_curried($name) || $c->get_cache_backend($name) );
117 # be nice and always return the same one for the simplest case
118 return ( $c->_default_curried_cache || $c->_default_curried_cache( $c->curry_cache( @meta ) ) );
120 return $c->curry_cache( @meta );
124 sub construct_curried_cache {
125 my ( $c, @meta ) = @_;
126 return $c->curried_cache_class( @meta )->new( @meta );
129 sub curried_cache_class {
130 my ( $c, @meta ) = @_;
131 $c->config->{cache}{curried_class} || "Catalyst::Plugin::Cache::Curried";
135 my ( $c, @meta ) = @_;
136 return $c->construct_curried_cache( $c, $c->_cache_caller_meta, @meta );
139 sub get_preset_curried {
140 my ( $c, $name ) = @_;
142 if ( ref( my $preset = $c->config->{cache}{profiles}{$name} ) ) {
143 return $preset if Scalar::Util::blessed($preset);
145 my @meta = ( ( ref $preset eq "HASH" ) ? %$preset : @$preset );
146 return $c->curry_cache( @meta );
152 sub get_cache_backend {
153 my ( $c, $name ) = @_;
154 $c->_cache_backends->{$name};
157 sub register_cache_backend {
158 my ( $c, $name, $backend ) = @_;
160 no warnings 'uninitialized';
161 Carp::croak("$backend does not look like a cache backend - "
162 . "it must be an object supporting get, set and remove")
163 unless eval { $backend->can("get") && $backend->can("set") && $backend->can("remove") };
165 $c->_cache_backends->{$name} = $backend;
168 sub unregister_cache_backend {
169 my ( $c, $name ) = @_;
170 delete $c->_cache_backends->{$name};
173 sub default_cache_backend {
175 $c->get_cache_backend( "default" ) || $c->temporary_cache_backend;
178 sub temporary_cache_backend {
180 die "FIXME - make up an in memory cache backend, that hopefully works well for the current engine";
183 sub _cache_caller_meta {
186 my ( $caller, $component, $controller );
188 for my $i ( 0 .. 15 ) { # don't look to far
189 my @info = caller(2 + $i) or last;
191 $caller ||= \@info unless $info[0] =~ /Plugin::Cache/;
192 $component ||= \@info if $info[0]->isa("Catalyst::Component");
193 $controller ||= \@info if $info[0]->isa("Catalyst::Controller");
195 last if $caller && $component && $controller;
198 my ( $caller_pkg, $component_pkg, $controller_pkg ) =
199 map { $_ ? $_->[0] : undef } $caller, $component, $controller;
202 'caller' => $caller_pkg,
203 component => $component_pkg,
204 controller => $controller_pkg,
205 caller_frame => $caller,
206 component_frame => $component,
207 controller_frame => $controller,
211 # this gets a shit name so that the plugins can override a good name
212 sub choose_cache_backend_wrapper {
213 my ( $c, @meta ) = @_;
215 Carp::croak("metadata must be an even sized list") unless @meta % 2 == 0;
219 unless ( exists $meta{'caller'} ) {
220 my %caller = $c->_cache_caller_meta;
221 @meta{keys %caller} = values %caller;
224 # allow the cache client to specify who it wants to cache with (but loeave room for a hook)
225 if ( exists $meta{backend} ) {
226 if ( Scalar::Util::blessed($meta{backend}) ) {
227 return $meta{backend};
229 return $c->get_cache_backend( $meta{backend} ) || $c->default_cache_backend;
233 if ( my $chosen = $c->choose_cache_backend( %meta ) ) {
234 $chosen = $c->get_cache_backend( $chosen ) unless Scalar::Util::blessed($chosen); # if it's a name find it
235 return $chosen if Scalar::Util::blessed($chosen); # only return if it was an object or name lookup worked
238 # die "no such backend"?
239 # currently, we fall back to default
242 return $c->default_cache_backend;
245 sub choose_cache_backend { shift->NEXT::choose_cache_backend( @_ ) } # a convenient fallback
248 my ( $c, $key, $value, %meta ) = @_;
249 $c->choose_cache_backend_wrapper( key => $key, value => $value, %meta )
250 ->set( $key, $value, exists $meta{expires} ? $meta{expires} : () );
254 my ( $c, $key, @meta ) = @_;
255 $c->choose_cache_backend_wrapper( key => $key, @meta )->get( $key );
259 my ( $c, $key, @meta ) = @_;
260 $c->choose_cache_backend_wrapper( key => $key, @meta )->remove( $key );
271 Catalyst::Plugin::Cache - Flexible caching support for Catalyst.
279 # configure a backend or use a store plugin
280 __PACKAGE__->config->{cache}{backend} = {
281 class => "Cache::Bounded",
288 my ( $self, $c, $id ) = @_;
290 my $cache = $c->cache;
294 unless ( $result = $cache->get( $id ) ) {
295 # ... calculate result ...
296 $c->cache->set( $id, $result );
302 This plugin gives you access to a variety of systems for caching
303 data. It allows you to use a very simple configuration API, while
304 maintaining the possibility of flexibility when you need it later.
306 Among its features are support for multiple backends, segmentation based
307 on component or controller, keyspace partitioning, and so more, in
308 various subsidiary plugins.
314 =item cache $profile_name
318 Return a curried object with metadata from C<$profile_name> or as
319 explicitly specified.
321 If a profile by the name C<$profile_name> doesn't exist, but a backend
322 object by that name does exist, the backend will be returned instead,
323 since the interface for curried caches and backends is almost identical.
325 This method can also be called without arguments, in which case is
326 treated as though the C<%meta> hash was empty.
328 See L</METADATA> for details.
330 =item curry_cache %meta
332 Return a L<Catalyst::Plugin::Cache::Curried> object, curried with C<%meta>.
334 See L</METADATA> for details.
336 =item cache_set $key, $value, %meta
338 =item cache_get $key, %meta
340 =item cache_remove $key, %meta
342 These cache operations will call L<choose_cache_backend> with %meta, and
343 then call C<set>, C<get>, or C<remove> on the resulting backend object.
345 =item choose_cache_backend %meta
347 Select a backend object. This should return undef if no specific backend
348 was selected - its caller will handle getting C<default_cache_backend>
351 This method is typically used by plugins.
353 =item get_cache_backend $name
355 Get a backend object by name.
357 =item default_cache_backend
359 Return the default backend object.
361 =item temporary_cache_backend
363 When no default cache backend is configured this method might return a
364 backend known to work well with the current L<Catalyst::Engine>. This is
375 Whenever you set or retrieve a key you may specify additional metadata
376 that will be used to select a specific backend.
378 This metadata is very freeform, and the only key that has any meaning by
379 default is the C<backend> key which can be used to explicitly choose a backend
382 The C<choose_cache_backend> method can be overridden in order to
383 facilitate more intelligent backend selection. For example,
384 L<Catalyst::Plugin::Cache::Choose::KeyRegexes> overrides that method to
385 select a backend based on key regexes.
387 Another example is a L<Catalyst::Plugin::Cache::ControllerNamespacing>,
388 which wraps backends in objects that perform key mangling, in order to
389 keep caches namespaced per controller.
391 However, this is generally left as a hook for larger, more complex
392 applications. Most configurations should make due XXXX
394 The simplest way to dynamically select a backend is based on the
395 L</Cache Profiles> configuration.
397 =head2 Meta Data Keys
399 C<choose_cache_backend> is called with some default keys.
405 Supplied by C<cache_get>, C<cache_set>, and C<cache_remove>.
409 Supplied by C<cache_set>.
413 The package name of the innermost caller that doesn't match
414 C<qr/Plugin::Cache/>.
418 The entire C<caller($i)> frame of C<caller>.
422 The package name of the innermost caller who C<isa>
423 L<Catalyst::Component>.
425 =item component_frame
427 This entire C<caller($i)> frame of C<component>.
431 The package name of the innermost caller who C<isa>
432 L<Catalyst::Controller>.
434 =item controller_frame
436 This entire C<caller($i)> frame of C<controller>.
440 =head2 Metadata Currying
442 In order to avoid specifying C<%meta> over and over again you may call
443 C<cache> or C<curry_cache> with C<%meta> once, and get back a B<curried
444 cache object>. This object responds to the methods C<get>, C<set>, and
445 C<remove>, by appending its captured metadata and delegating them to
446 C<cache_get>, C<cache_set>, and C<cache_remove>.
448 This is simpler than it sounds.
450 Here is an example using currying:
452 my $cache = $c->cache( %meta ); # cache is curried
454 $cache->set( $key, $value );
458 And here is an example without using currying:
460 $c->cache_set( $key, $value, %meta );
462 $c->cache_get( $key, %meta );
464 See L<Catalyst::Plugin::Cache::Curried> for details.
468 $c->config->{cache} = {
472 All configuration parameters should be provided in a hash reference
473 under the C<cache> key in the C<config> hash.
475 =head2 Backend Configuration
477 Configuring backend objects is done by adding hash entries under the
478 C<backends> key in the main config.
480 A special case is that the hash key under the C<backend> (singular) key
481 of the main config is assumed to be the backend named C<default>.
487 Instantiate a backend from a L<Cache> compatible class. E.g.
489 $c->config->{cache}{backends}{small_things} = {
490 class => "Cache::Bounded",
495 $c->config->{cache}{backends}{large_things} = {
496 class => "Cache::Memcached",
497 data => '1.2.3.4:1234',
500 The options in the hash are passed to the class's C<new> method.
502 The class will be C<required> as necessary during setup time.
506 Instantiate a backend using a store plugin, e.g.
508 $c->config->{cache}{backend} = {
512 Store plugins typically require less configuration because they are
513 specialized for L<Catalyst> applications. For example
514 L<Catalyst::Plugin::Cache::Store::FastMmap> will specify a default
515 C<share_file>, and additionally use a subclass of L<Cache::FastMmap>
516 that can also store non reference data.
518 The store plugin must be loaded.
522 =head2 Cache Profiles
528 Supply your own predefined profiles for cache metadata, when using the
531 For example when you specify
533 $c->config->{cache}{profiles}{thumbnails} = {
534 backend => "large_things",
537 And then get a cache object like this:
539 $c->cache("thumbnails");
541 It is the same as if you had done:
543 $c->cache( backend => "large_things" );
547 =head2 Miscellaneous Configuration
553 When you do not specify a C<store> parameter in the backend
554 configuration this one will be used instead. This configuration
555 parameter is not necessary if only one store plugin is loaded.
565 An object that responds to the methods detailed in
566 L<Catalyst::Plugin::Cache::Backend> (or more).
570 A plugin that provides backends of a certain type. This is a bit like a
575 Stored key/value pairs of data for easy re-access.
579 "Extra" information about the item being stored, which can be used to
580 locate an appropriate backend.
584 my $cache = $c->cache(type => 'thumbnails');
585 $cache->set('pic01', $thumbnaildata);
587 A cache which has been pre-configured with a particular set of
588 namespacing data. In the example the cache returned could be one
589 specifically tuned for storing thumbnails.
591 An object that responds to C<get>, C<set>, and C<remove>, and will
592 automatically add metadata to calls to C<< $c->cache_get >>, etc.
598 L<Cache> - the generic cache API on CPAN.
600 L<Catalyst::Plugin::Cache::Store> - how to write a store plugin.
602 L<Catalyst::Plugin::Cache::Curried> - the interface for curried caches.
604 L<Catalyst::Plugin::Cache::Choose::KeyRegexes> - choose a backend based on
605 regex matching on the keys. Can be used to partition the keyspace.
607 L<Catalyst::Plugin::Cache::ControllerNamespacing> - wrap backend objects in a
608 name mangler so that every controller gets its own keyspace.
612 Yuval Kogman, C<nothingmuch@woobling.org>
614 =head1 COPYRIGHT & LICENSE
616 Copyright (c) Yuval Kogman, 2006. All rights reserved.
618 This library is free software, you can redistribute it and/or modify it under
619 the same terms as Perl itself, as well as under the terms of the MIT license.