# man > Cache

---
type: CommandReference
command: Cache
mode: perldoc
section: 3pm
source: perldoc
---

## Quick Reference

- `use Cache::File; my $c = Cache::File->new( cache_root => '/tmp/cacheroot' )` — instantiate a file-based cache
- `$c->get($key)` — retrieve data for a key
- `$c->set($key, $data, $expiry)` — store data with optional expiry
- `$c->entry($key)` — return a `Cache::Entry` object for fine-grained manipulation
- `$c->purge()` — remove expired entries
- `$c->clear()` — remove all entries
- `$c->count()` — number of entries in the cache
- `tie %hash, 'Cache::File', { cache_root => $dir }` — use cache via a tied hash

## Name

Cache — the Cache interface for persisting data for a specified period.

## Synopsis

perl
use Cache::File;

my $cache = Cache::File->new( cache_root => '/tmp/cacheroot' );
my $customer = $cache->get( $name );

unless ($customer) {
    $customer = get_customer_from_db( $name );
    $cache->set( $name, $customer, '10 minutes' );
}

return $customer;
Tie interface:

perl
tie %hash, 'Cache::File', { cache_root => $tempdir };
$hash{'key'} = 'some data';
$data = $hash{'key'};
## Options (Properties for `new()`)

- `default_expires` — default expiry time for new entries. Get/set with `$c->default_expires()` and `$c->set_default_expires($expiry)`
- `removal_strategy` — strategy object (e.g., `Cache::RemovalStrategy::LRU`, `Cache::RemovalStrategy::FIFO`) or package name. Get with `$c->removal_strategy()`
- `size_limit` — maximum cache size in bytes. Get with `$c->size_limit()`
- `load_callback` — function called on a `get` miss. Get/set with `$c->load_callback()` / `$c->set_load_callback($func)`
- `validate_callback` — function called on a `get` miss. Get/set with `$c->validate_callback()` / `$c->set_validate_callback($func)`

## Methods

### Core Methods

- `$c->entry($key)` — return a `Cache::Entry` object for the given key
- `$c->purge()` — remove all expired data
- `$c->clear()` — remove all entries regardless of expiry
- `$c->count()` — number of entries in the cache
- `$c->size()` — size of the cache in bytes

### Shortcut Methods (wrappers for `$c->entry($key)->method()`)

- `$c->exists($key)` — check if key exists
- `$c->set($key, $data, [$expiry])` — store data
- `$c->get($key)` — retrieve data
- `$c->remove($key)` — delete entry
- `$c->expiry($key)` — get expiry time
- `$c->set_expiry($key, $time)` — set expiry
- `$c->handle($key, [$mode, [$expiry]])` — get filehandle for entry
- `$c->validity($key)` — get validity data
- `$c->set_validity($key, $data)` — set validity data
- `$c->freeze($key, $data, [$expiry])` — store serialized data
- `$c->thaw($key)` — retrieve and deserialize data

### Removal Strategy Methods (for internal use)

- `$c->remove_oldest()` — remove oldest entry, returns its size
- `$c->remove_stalest()` — remove least used entry, returns its size
- `$c->check_size($size)` — call after cache size increases; invokes removal strategy if needed

### Utility Methods (for internal use)

- `Cache::Canonicalize_Expiration_Time($timespec)` — convert a timespec to Unix time

## Examples

### Basic usage

perl
use Cache::File;
my $cache = Cache::File->new( cache_root => '/tmp/cacheroot' );
my $data = $cache->get('mykey');
unless ($data) {
    $data = compute_expensive_value();
    $cache->set('mykey', $data, '1 hour');
}
print $data;
### Using the entry object

perl
my $entry = $cache->entry('mykey');
if ($entry->exists) {
    $entry->set_expiry('+1 day');
    my $data = $entry->get;
}
### Tied hash with load_callback

perl
tie my %cache, 'Cache::File', {
    cache_root    => '/tmp/cacheroot',
    load_callback => sub { my $key = shift; fetch_from_db($key) }
};
my $value = $cache{'some_key'};  # auto-loads on miss
## See Also

- [Cache::Entry](https://www.chedong.com/phpMan.php/perldoc/Cache%3A%3AEntry/markdown)
- [Cache::File](https://www.chedong.com/phpMan.php/perldoc/Cache%3A%3AFile/markdown)
- [Cache::RemovalStrategy](https://www.chedong.com/phpMan.php/perldoc/Cache%3A%3ARemovalStrategy/markdown)
- [Cache::Cache](https://www.chedong.com/phpMan.php/perldoc/Cache%3A%3ACache/markdown) — older interface; note differences:
  - `get`/`set` do not serialize complex data types (use `freeze`/`thaw`)
  - No `get_object`/`set_object`; use `entry` and `Cache::Entry`
  - No namespace concept in base interface
  - Automatic purging is implementation-specific
  - `Cache::File` no longer supports separate masks for entries and directories