1Catalyst::Plugin::CacheU(s3e)r Contributed Perl DocumentaCtaitoanlyst::Plugin::Cache(3)
2
3
4

NAME

6       Catalyst::Plugin::Cache - Flexible caching support for Catalyst.
7

SYNOPSIS

9               use Catalyst qw/
10               Cache
11           /;
12
13           # 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
19           # 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
26
27           # In a controller:
28
29           sub foo : Local {
30               my ( $self, $c, $id ) = @_;
31
32               my $cache = $c->cache;
33
34               my $result;
35
36               unless ( $result = $cache->get( $id ) ) {
37                   # ... calculate result ...
38                   $c->cache->set( $id, $result );
39               }
40           };
41

DESCRIPTION

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
47       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

METHODS

52       cache $profile_name
53       cache %meta
54           Return a curried object with metadata from $profile_name or as
55           explicitly specified.
56
57           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
62           This method can also be called without arguments, in which case is
63           treated as though the %meta hash was empty.
64
65           See "METADATA" for details.
66
67       curry_cache %meta
68           Return a Catalyst::Plugin::Cache::Curried object, curried with
69           %meta.
70
71           See "METADATA" for details.
72
73       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
81           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
86       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
91           This method is typically used by plugins.
92
93       get_cache_backend $name
94           Get a backend object by name.
95
96       default_cache_backend
97           Return the default backend object.
98
99       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
104
105

METADATA

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
111       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
115       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
120       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
124       However, this is generally left as a hook for larger, more complex
125       applications. Most configurations should make due XXXX
126
127       The simplest way to dynamically select a backend is based on the "Cache
128       Profiles" configuration.
129
130   Meta Data Keys
131       "choose_cache_backend" is called with some default keys.
132
133       key Supplied by "cache_get", "cache_set", and "cache_remove".
134
135       value
136           Supplied by "cache_set".
137
138       caller
139           The package name of the innermost caller that doesn't match
140           "qr/Plugin::Cache/".
141
142       caller_frame
143           The entire "caller($i)" frame of "caller".
144
145       component
146           The package name of the innermost caller who "isa"
147           Catalyst::Component.
148
149       component_frame
150           This entire "caller($i)" frame of "component".
151
152       controller
153           The package name of the innermost caller who "isa"
154           Catalyst::Controller.
155
156       controller_frame
157           This entire "caller($i)" frame of "controller".
158
159   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
166       This is simpler than it sounds.
167
168       Here is an example using currying:
169
170           my $cache = $c->cache( %meta ); # cache is curried
171
172           $cache->set( $key, $value );
173
174           $cache->get( $key );
175
176       And here is an example without using currying:
177
178           $c->cache_set( $key, $value, %meta );
179
180           $c->cache_get( $key, %meta );
181
182       See Catalyst::Plugin::Cache::Curried for details.
183

CONFIGURATION

185           $c->config->{'Plugin::Cache'} = {
186               ...
187           };
188
189       All configuration parameters should be provided in a hash reference
190       under the "Plugin::Cache" key in the "config" hash.
191
192   Backend Configuration
193       Configuring backend objects is done by adding hash entries under the
194       "backends" key in the main config.
195
196       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
199       class
200           Instantiate a backend from a Cache compatible class. E.g.
201
202               $c->config->{'Plugin::Cache'}{backends}{small_things} = {
203                   class    => "Cache::Bounded",
204                   interval => 1000,
205                   size     => 10000,
206               };
207
208               $c->config->{'Plugin::Cache'}{backends}{large_things} = {
209                   class => "Cache::Memcached",
210                   data  => '1.2.3.4:1234',
211               };
212
213           The options in the hash are passed to the class's "new" method.
214
215           The class will be "required" as necessary during setup time.
216
217       store
218           Instantiate a backend using a store plugin, e.g.
219
220               $c->config->{'Plugin::Cache'}{backend} = {
221                   store => "FastMmap",
222               };
223
224           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
230           The store plugin must be loaded.
231
232   Cache Profiles
233       profiles
234           Supply your own predefined profiles for cache metadata, when using
235           the "cache" method.
236
237           For example when you specify
238
239               $c->config->{'Plugin::Cache'}{profiles}{thumbnails} = {
240                   backend => "large_things",
241               };
242
243           And then get a cache object like this:
244
245               $c->cache("thumbnails");
246
247           It is the same as if you had done:
248
249               $c->cache( backend => "large_things" );
250
251   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

TERMINOLOGY

258       backend
259           An object that responds to the methods detailed in
260           Catalyst::Plugin::Cache::Backend (or more).
261
262       store
263           A plugin that provides backends of a certain type. This is a bit
264           like a factory.
265
266       cache
267           Stored key/value pairs of data for easy re-access.
268
269       metadata
270           "Extra" information about the item being stored, which can be used
271           to locate an appropriate backend.
272
273       curried cache
274             my $cache = $c->cache(type => 'thumbnails');
275             $cache->set('pic01', $thumbnaildata);
276
277           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
281           An object that responds to "get", "set", and "remove", and will
282           automatically add metadata to calls to "$c->cache_get", etc.
283

SEE ALSO

285       Cache - the generic cache API on CPAN.
286
287       Catalyst::Plugin::Cache::Store - how to write a store plugin.
288
289       Catalyst::Plugin::Cache::Curried - the interface for curried caches.
290
291       Catalyst::Plugin::Cache::Choose::KeyRegexes - choose a backend based on
292       regex matching on the keys. Can be used to partition the keyspace.
293
294       Catalyst::Plugin::Cache::ControllerNamespacing - wrap backend objects
295       in a name mangler so that every controller gets its own keyspace.
296

AUTHOR

298       Yuval Kogman, "nothingmuch@woobling.org"
299
300       Jos Boumans, "kane@cpan.org"
301
303       Copyright (c) Yuval Kogman, 2006. All rights reserved.
304
305       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

POD ERRORS

310       Hey! The above document had some coding errors, which are explained
311       below:
312
313       Around line 444:
314           Expected text after =item, not a bullet
315
316
317
318perl v5.32.0                      2020-07-28        Catalyst::Plugin::Cache(3)
Impressum