| 1 |
NAME |
| 2 |
App::Cache - Easy application-level caching |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
# in your class: |
| 6 |
my $cache = App::Cache->new({ ttl => 60*60 }); |
| 7 |
$cache->delete('test'); |
| 8 |
my $data = $cache->get('test'); |
| 9 |
my $code = $cache->get_code("code", sub { $self->calculate() }); |
| 10 |
my $html = $cache->get_url("http://www.google.com/"); |
| 11 |
$cache->set('test', 'one'); |
| 12 |
$cache->set('test', { foo => 'bar' }); |
| 13 |
my $scratch = $cache->scratch; |
| 14 |
$cache->clear; |
| 15 |
|
| 16 |
DESCRIPTION |
| 17 |
The App::Cache module lets an application cache data locally. There are |
| 18 |
a few times an application would need to cache data: when it is |
| 19 |
retrieving information from the network or when it has to complete a |
| 20 |
large calculation. |
| 21 |
|
| 22 |
For example, the Parse::BACKPAN::Packages module downloads a file off |
| 23 |
the net and parses it, creating a data structure. Only then can it |
| 24 |
actually provide any useful information for the programmer. |
| 25 |
Parse::BACKPAN::Packages uses App::Cache to cache both the file download |
| 26 |
and data structures, providing much faster use when the data is cached. |
| 27 |
|
| 28 |
This module stores data in the home directory of the user, in a dot |
| 29 |
directory. For example, the Parse::BACKPAN::Packages cache is actually |
| 30 |
stored underneath "~/.parse_backpan_packages/cache/". This is so that |
| 31 |
permisssions are not a problem - it is a per-user, per-application |
| 32 |
cache. |
| 33 |
|
| 34 |
METHODS |
| 35 |
new |
| 36 |
The constructor creates an App::Cache object. It takes three optional |
| 37 |
parameters: |
| 38 |
|
| 39 |
* ttl contains the number of seconds in which a cache entry expires. |
| 40 |
The default is 30 minutes. |
| 41 |
|
| 42 |
my $cache = App::Cache->new({ ttl => 30*60 }); |
| 43 |
|
| 44 |
* application sets the application name. If you are calling new() from |
| 45 |
a class, the application is automagically set to the calling class, |
| 46 |
so you should rarely need to pass it in: |
| 47 |
|
| 48 |
my $cache = App::Cache->new({ application => 'Your::Module' }); |
| 49 |
|
| 50 |
* directory sets the directory to be used for the cache. Normally this |
| 51 |
is just set for you and will be based on the application name and be |
| 52 |
created in the users home directory. Sometimes for testing, it can |
| 53 |
be useful to set this. |
| 54 |
|
| 55 |
my $cache = App::Cache->new({ directory => '/tmp/your/cache/dir' }); |
| 56 |
|
| 57 |
* enabled can be set to 0 for testing, in which case you will always |
| 58 |
get cache misses: |
| 59 |
|
| 60 |
my $cache = App::Cache->new({ enabled => 0 }); |
| 61 |
|
| 62 |
clear |
| 63 |
Clears the cache: |
| 64 |
|
| 65 |
$cache->clear; |
| 66 |
|
| 67 |
delete |
| 68 |
Deletes an entry in the cache: |
| 69 |
|
| 70 |
$cache->delete('test'); |
| 71 |
|
| 72 |
get |
| 73 |
Gets an entry from the cache. Returns undef if the entry does not exist |
| 74 |
or if it has expired: |
| 75 |
|
| 76 |
my $data = $cache->get('test'); |
| 77 |
|
| 78 |
get_code |
| 79 |
This is a convenience method. Gets an entry from the cache, but if the |
| 80 |
entry does not exist, set the entry to the value of the code reference |
| 81 |
passed: |
| 82 |
|
| 83 |
my $code = $cache->get_code("code", sub { $self->calculate() }); |
| 84 |
|
| 85 |
get_url |
| 86 |
This is a convenience method. Gets the content of a URL from the cache, |
| 87 |
but if the entry does not exist, set the entry to the content of the URL |
| 88 |
passed: |
| 89 |
|
| 90 |
my $html = $cache->get_url("http://www.google.com/"); |
| 91 |
|
| 92 |
scratch |
| 93 |
Returns a directory in the cache that the application may use for |
| 94 |
scratch files: |
| 95 |
|
| 96 |
my $scratch = $cache->scratch; |
| 97 |
|
| 98 |
set |
| 99 |
Set an entry in the cache. Note that an entry value may be an arbitrary |
| 100 |
Perl data structure: |
| 101 |
|
| 102 |
$cache->set('test', 'one'); |
| 103 |
$cache->set('test', { foo => 'bar' }); |
| 104 |
|
| 105 |
directory |
| 106 |
Returns the full path to the cache directory. Primarily useful for when |
| 107 |
you are writing tests that use App::Cache and want to clean up after |
| 108 |
yourself. If you are doing that you may want to explicitly set the |
| 109 |
'application' constructor parameter to avoid later cleaning up a cache |
| 110 |
dir that was already in use. |
| 111 |
|
| 112 |
my $dir = $cache->directory; |
| 113 |
|
| 114 |
AUTHOR |
| 115 |
Leon Brocard <[email protected]> |
| 116 |
|
| 117 |
COPYRIGHT |
| 118 |
Copyright (C) 2005-7, Leon Brocard |
| 119 |
|
| 120 |
LICENSE |
| 121 |
This module is free software; you can redistribute it or modify it under |
| 122 |
the same terms as Perl itself. |
| 123 |
|