1Catalyst::Plugin::CacheU(s3e)r Contributed Perl DocumentaCtaitoanlyst::Plugin::Cache(3)
2
6 Catalyst::Plugin::Cache - Flexible caching support for Catalyst.
7
9 use Catalyst qw/
10 Cache
11 /;
12 # configure a backend or use a store plugin
14 __PACKAGE__->config->{'Plugin::Cache'}{backend} = {
15 class => "Cache::Bounded",
16 # ... params for Cache::Bounded...
17 };
18 # typical example for Cache::Memcached::libmemcached
20 __PACKAGE__->config->{'Plugin::Cache'}{backend} = {
21 class => "Cache::Memcached::libmemcached",
22 servers => ['127.0.0.1:11211'],
23 debug => 2,
24 };
25 # In a controller:
28 sub foo : Local {
30 my ( $self, $c, $id ) = @_;
31 my $cache = $c->cache;
33 my $result;
35 unless ( $result = $cache->get( $id ) ) {
37 # ... calculate result ...
38 $c->cache->set( $id, $result );
39 }
40 };
41
43 This plugin gives you access to a variety of systems for caching data.
44 It allows you to use a very simple configuration API, while maintaining
45 the possibility of flexibility when you need it later.
46 Among its features are support for multiple backends, segmentation
48 based on component or controller, keyspace partitioning, and so more,
49 in various subsidiary plugins.
50
52 cache $profile_name
53 cache %meta
54 Return a curried object with metadata from $profile_name or as
55 explicitly specified.
56 If a profile by the name $profile_name doesn't exist, but a backend
58 object by that name does exist, the backend will be returned
59 instead, since the interface for curried caches and backends is
60 almost identical.
61 This method can also be called without arguments, in which case is
63 treated as though the %meta hash was empty.
64 See "METADATA" for details.
66 curry_cache %meta
68 Return a Catalyst::Plugin::Cache::Curried object, curried with
69 %meta.
70 See "METADATA" for details.
72 cache_set $key, $value, %meta
74 cache_get $key, %meta
75 cache_remove $key, %meta
76 cache_compute $key, $code, %meta
77 These cache operations will call choose_cache_backend with %meta,
78 and then call "set", "get", "remove", or "compute" on the resulting
79 backend object.
80 If the backend object does not support "compute" then we emulate it
82 by calling cache_get, and if the returned value is undefined we
83 call the passed code reference, stores the returned value with
84 cache_set, and then returns the value. Inspired by CHI.
85 choose_cache_backend %meta
87 Select a backend object. This should return undef if no specific
88 backend was selected - its caller will handle getting
89 "default_cache_backend" on its own.
90 This method is typically used by plugins.
92 get_cache_backend $name
94 Get a backend object by name.
95 default_cache_backend
97 Return the default backend object.
98 temporary_cache_backend
100 When no default cache backend is configured this method might
101 return a backend known to work well with the current
102 Catalyst::Engine. This is a stub.
103
107 Introduction
108 Whenever you set or retrieve a key you may specify additional metadata
109 that will be used to select a specific backend.
110 This metadata is very freeform, and the only key that has any meaning
112 by default is the "backend" key which can be used to explicitly choose
113 a backend by name.
114 The "choose_cache_backend" method can be overridden in order to
116 facilitate more intelligent backend selection. For example,
117 Catalyst::Plugin::Cache::Choose::KeyRegexes overrides that method to
118 select a backend based on key regexes.
119 Another example is a Catalyst::Plugin::Cache::ControllerNamespacing,
121 which wraps backends in objects that perform key mangling, in order to
122 keep caches namespaced per controller.
123 However, this is generally left as a hook for larger, more complex
125 applications. Most configurations should make due XXXX
126 The simplest way to dynamically select a backend is based on the "Cache
128 Profiles" configuration.
129 Meta Data Keys
131 "choose_cache_backend" is called with some default keys.
132 key Supplied by "cache_get", "cache_set", and "cache_remove".
134 value
136 Supplied by "cache_set".
137 caller
139 The package name of the innermost caller that doesn't match
140 "qr/Plugin::Cache/".
141 caller_frame
143 The entire "caller($i)" frame of "caller".
144 component
146 The package name of the innermost caller who "isa"
147 Catalyst::Component.
148 component_frame
150 This entire "caller($i)" frame of "component".
151 controller
153 The package name of the innermost caller who "isa"
154 Catalyst::Controller.
155 controller_frame
157 This entire "caller($i)" frame of "controller".
158 Metadata Currying
160 In order to avoid specifying %meta over and over again you may call
161 "cache" or "curry_cache" with %meta once, and get back a curried cache
162 object. This object responds to the methods "get", "set", and "remove",
163 by appending its captured metadata and delegating them to "cache_get",
164 "cache_set", and "cache_remove".
165 This is simpler than it sounds.
167 Here is an example using currying:
169 my $cache = $c->cache( %meta ); # cache is curried
171 $cache->set( $key, $value );
173 $cache->get( $key );
175 And here is an example without using currying:
177 $c->cache_set( $key, $value, %meta );
179 $c->cache_get( $key, %meta );
181 See Catalyst::Plugin::Cache::Curried for details.
183
185 $c->config->{'Plugin::Cache'} = {
186 ...
187 };
188 All configuration parameters should be provided in a hash reference
190 under the "Plugin::Cache" key in the "config" hash.
191 Backend Configuration
193 Configuring backend objects is done by adding hash entries under the
194 "backends" key in the main config.
195 A special case is that the hash key under the "backend" (singular) key
197 of the main config is assumed to be the backend named "default".
198 class
200 Instantiate a backend from a Cache compatible class. E.g.
201 $c->config->{'Plugin::Cache'}{backends}{small_things} = {
203 class => "Cache::Bounded",
204 interval => 1000,
205 size => 10000,
206 };
207 $c->config->{'Plugin::Cache'}{backends}{large_things} = {
209 class => "Cache::Memcached",
210 data => '1.2.3.4:1234',
211 };
212 The options in the hash are passed to the class's "new" method.
214 The class will be "required" as necessary during setup time.
216 store
218 Instantiate a backend using a store plugin, e.g.
219 $c->config->{'Plugin::Cache'}{backend} = {
221 store => "FastMmap",
222 };
223 Store plugins typically require less configuration because they are
225 specialized for Catalyst applications. For example
226 Catalyst::Plugin::Cache::Store::FastMmap will specify a default
227 "share_file", and additionally use a subclass of Cache::FastMmap
228 that can also store non reference data.
229 The store plugin must be loaded.
231 Cache Profiles
233 profiles
234 Supply your own predefined profiles for cache metadata, when using
235 the "cache" method.
236 For example when you specify
238 $c->config->{'Plugin::Cache'}{profiles}{thumbnails} = {
240 backend => "large_things",
241 };
242 And then get a cache object like this:
244 $c->cache("thumbnails");
246 It is the same as if you had done:
248 $c->cache( backend => "large_things" );
250 Miscellaneous Configuration
252 default_store
253 When you do not specify a "store" parameter in the backend
254 configuration this one will be used instead. This configuration
255 parameter is not necessary if only one store plugin is loaded.
256
258 backend
259 An object that responds to the methods detailed in
260 Catalyst::Plugin::Cache::Backend (or more).
261 store
263 A plugin that provides backends of a certain type. This is a bit
264 like a factory.
265 cache
267 Stored key/value pairs of data for easy re-access.
268 metadata
270 "Extra" information about the item being stored, which can be used
271 to locate an appropriate backend.
272 curried cache
274 my $cache = $c->cache(type => 'thumbnails');
275 $cache->set('pic01', $thumbnaildata);
276 A cache which has been pre-configured with a particular set of
278 namespacing data. In the example the cache returned could be one
279 specifically tuned for storing thumbnails.
280 An object that responds to "get", "set", and "remove", and will
282 automatically add metadata to calls to "$c->cache_get", etc.
283
285 Cache - the generic cache API on CPAN.
286 Catalyst::Plugin::Cache::Store - how to write a store plugin.
288 Catalyst::Plugin::Cache::Curried - the interface for curried caches.
290 Catalyst::Plugin::Cache::Choose::KeyRegexes - choose a backend based on
292 regex matching on the keys. Can be used to partition the keyspace.
293 Catalyst::Plugin::Cache::ControllerNamespacing - wrap backend objects
295 in a name mangler so that every controller gets its own keyspace.
296
298 Yuval Kogman, "nothingmuch@woobling.org"
299 Jos Boumans, "kane@cpan.org"
301
303 Copyright (c) Yuval Kogman, 2006. All rights reserved.
304 This library is free software, you can redistribute it and/or modify it
306 under the same terms as Perl itself, as well as under the terms of the
307 MIT license.
308
310 Hey! The above document had some coding errors, which are explained
311 below:
312 Around line 444:
314 Expected text after =item, not a bullet
315perl v5.32.0 2020-07-28 Catalyst::Plugin::Cache(3)