NAME
Tie::Cache::Autoupdater - a tied hash whose values refresh themselves on a timeout
VERSION
This documentation refers to Tie::Cache::Autoupdater version 0.22
SYNOPSIS
use Tie::Cache::Autoupdater;
tie my %cache, 'Tie::Cache::Autoupdater',
settings => { source => \&read_settings_from_db, timeout => 60 },
counters => { source => \&count_table_rows, timeout => 10 };
# Every read returns the cached value, or calls the source subroutine
# again and caches the new result if the timeout has expired.
my $settings = $cache{settings};
my $counters = $cache{counters};
# Keys can also be registered after the hash has been tied.
$cache{file_count} = {
source => sub { scalar glob "$path/*" },
timeout => 2.5, # fractional timeouts need Time::HiRes
};
# Ask for a deep copy if the caller is going to modify the data.
$cache{report} = {
source => \&build_report,
timeout => 30,
clone => 1,
};
DESCRIPTION
Long-running processes - FastCGI workers, daemons, queue consumers - often need data that changes rarely, but not never: site settings, row counters, a price list, a feature flag. Fetching it from the database on every request is wasteful, and fetching it once at start-up is wrong: the process may stay alive for days or weeks, while the data behind it changes every few minutes.
This module ties a hash to a set of named data sources. You register a key with a subroutine and a timeout, and from then on reading that key gives you the cached value until the timeout expires. The first read after expiry calls the subroutine again, and its result becomes the new cached value.
The refresh is lazy: it happens inside the read itself. There is no timer, no background process and no extra thread, so a key that nobody reads is never refreshed, and the source subroutine is called at most once per timeout no matter how many times the key is read.
Registering keys
A key can be registered when the hash is tied:
tie my %cache, 'Tie::Cache::Autoupdater', db_query => {
timeout => 10,
source => sub {
my $sth = $DBH->prepare('select * from table');
$sth->execute;
return $sth->fetchall_arrayref;
}
};
or at any time afterwards, by assigning to it:
$cache{db_query} = {
timeout => 10,
source => sub {
my $sth = $DBH->prepare('select * from table');
$sth->execute;
return $sth->fetchall_arrayref;
}
};
Both forms are equivalent, and there is no limit on the number of keys. Note that an assignment does not store a value - it describes where the value comes from. Assigning to a key that is already registered replaces its description and discards whatever was cached for it, so the next read calls the new source immediately.
Parameters
Each key is described by a hash reference with the following fields.
source
A reference to the subroutine that produces the value. It is called with no arguments, in list context. Required: a key registered without it produces a warning and undef on the first read.
timeout
How long a cached value stays fresh, in seconds. Defaults to 1 second. With Time::HiRes installed the timeout may be fractional; without it, values below 1 second simply mean "refresh on every read whose timestamp differs".
In the example below the value of db_counters is refreshed at most once every 0.2 seconds, and the value of file_count at most once every 2.5 seconds:
tie %cache, 'Tie::Cache::Autoupdater',
db_counters => {
timeout => 0.2,
source => sub {
my $sth = $DBH->prepare('select count(*) from table2');
$sth->execute;
return ($sth->fetchrow_array);
}
},
file_count => {
timeout => 2.5,
source => sub { return scalar glob "$path/*" }
};
A false timeout (0, undef, an empty string) is replaced by the default of 1 second rather than meaning "never cache".
clone
Whether to return a deep copy of the cached data instead of the cached data itself. Off by default. See "Sharing and cloning" below.
What gets cached
The source subroutine is called in list context, and what it returns is normalised before being stored:
a single value is cached as it is, whether it is a plain scalar or a reference;
two or more values are cached as a reference to an array holding them;
an empty list is cached as
undef.
So a source that ends with return ($count, $sum) yields an array reference, while a source that ends with return $hashref yields that same hash reference. If you want a structure back, return a reference to it explicitly - returning a plain list of key/value pairs gives you an array reference, not a hash.
Sharing and cloning
By default the cached value is returned as it is. For a reference this means every caller receives the very reference that the cache holds, so modifying the returned data silently modifies the cache, and every later read sees the change until the timeout expires.
Set clone to a true value to get a fresh deep copy on every read:
$cache{settings} = {
source => \&read_settings_from_db,
timeout => 60,
clone => 1,
};
my $settings = $cache{settings};
$settings->{theme} = 'dark'; # affects this copy only
Cloning is done with Storable::dclone and applies to references only; plain scalars are returned unchanged, with or without the flag. Because the copy is made on every single read, leave clone off when callers treat the data as read-only - it is the cheaper and the common case.
dclone cannot copy code references, globs, file handles or Storable-hostile objects, and will die on them. A source returning such data has to be used without clone.
Error handling
The source subroutine is called inside eval. If it dies, the module emits a warning naming the key and the error:
Check source subroutine for key db_query. Error - DBI connect failed ...
the read returns undef, and the timestamp of the key is left untouched, so the next read retries immediately instead of waiting for the timeout. A value cached by an earlier successful call stays in the cache but is not returned by the failed read; it will be returned again only if a later call succeeds.
Reading a key that was never registered returns undef quietly, without calling anything and without a warning.
Standard hash operations
The tied hash supports the usual operations, with the cache in mind:
exists $cache{key}-
True if the key is registered. It never calls the source subroutine and says nothing about whether a value is currently cached.
delete $cache{key}-
Unregisters the key and throws away its cached value.
keys %cache,each %cache-
keyslists the registered keys.eachreturns a key and its value, and the value goes through a normal read - so iterating may call source subroutines and refresh expired keys. %cache = ()-
Unregisters every key.
untie %cache-
Stops the tie; the cached data is released with the underlying object.
DEPENDENCIES
Storable - core module, used for
clone.Time::HiRes - core module, optional. Loaded at compile time if available, and then used instead of the built-in
timeso that fractional timeouts work.
CAVEATS
The cache lives in the memory of one process. Under a pre-forking server each worker keeps its own independent copy, with its own timestamps, so different workers may hold different values for the same key at the same moment. The module performs no locking and does nothing to coordinate workers; if you need a cache shared between processes, this is not it.
Because the refresh is driven by reads, the age of a value is bounded by the timeout only for keys that are read regularly. A key read once an hour with a timeout of 10 seconds is refreshed once an hour, not every 10 seconds.
AUTHOR
Anton Morozov (antonfin@cpan.org)
DEVELOPMENT
Repository
http://github.com/antonfin/Tie-Cache-Autoupdater
LICENSE AND COPYRIGHT
Copyright (c) 2011-2026 by Anton Morozov (antonfin@cpan.org).
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See the LICENSE file in the distribution for the full text.