NAME

Cache::CacheFactory::Expiry::Size - Size-based expiry policy for Cache::CacheFactory.

DESCRIPTION

Cache::CacheFactory::Expiry::Size is a size-based expiry (pruning and validity) policy for Cache::CacheFactory.

It provides similar functionality and backwards-compatibility with the max_size option of Cache::SizeAwareFileCache and variants.

It's highly recommended that you DO NOT use this policy as a validity policy, as calculating the size of the contents of the cache on each read can be quite expensive, and it's semantically ambiguous as to just what behaviour is intended by it anyway.

Note that in its current implementation Cache::CacheFactory::Expiry::Size is "working but highly inefficient" when it comes to purging. It is provided mostly for completeness while a revised version is being worked on.

SIZE SPECIFICATIONS

Currently all size values must be specified as numbers and will be interpreted as bytes. Future versions reserve the right to supply the size as a string '10 M' for ease of use, but this is not currently implemented.

STARTUP OPTIONS

The following startup options may be supplied to Cache::CacheFactory::Expiry::Size, see the Cache::CacheFactory documentation for how to pass options to a policy.

max_size => $size

This sets the maximum size that the cache strives to keep under, any items that take the cache over this size will be pruned (for a pruning policy) at the next $cache->purge().

See the "SIZE SPECIFICATIONS" section above for details on what values you can pass in as $size.

You can also use Cache::CacheFactory::$NO_MAX_SIZE to indicate that there is no size limit automatically applied, this is generally a bit pointless with a 'size' policy unless you are going to call limit_size() manually every so often.

Note that by default pruning policies are not immediately enforced, they are only applied when a $cache->purge() occurs. This means that it is possible (likely even) for the size of the cache to exceed max_size at least on a temporary basis. When the next $cache->purge() occurs, the cache will be reduced back down below max_size.

If you make use of the auto_purge_on_set option to Cache::CacheFactory, you'll cause a $cache->purge() on a regular basis depending on the value of auto_purge_interval.

However, even with the most aggressive values of auto_purge_interval there will still be a best-case scenario of the cache entry being written to the cache, taking it over max_size, and the purge then reducing the cache to or below max_size. This is essentially unavoidable since it's impossible to know the size an entry will take in the cache until it has been written.

Also note that for each purge() the cache will need to call size() once (or more if no_cache_cache_size_during_purge is set), which on most storage policies will involve inspecting the size of every key in that namespace. Needless to say this can be quite an expensive operation.

With these points in mind you may consider setting max_size to $NO_MAX_SIZE and manually calling $cache->limit_size( $size ) periodically at a time that's under your control.

no_cache_cache_size_during_purge => 0 | 1

By default, to reduce the number of calls to $storage->size() during a purge, the size of the cache will be stored locally at the start of a purge and estimated as keys are purged.

For the most part this is reasonable behaviour, however if the estimated reduction from deleting a key is wrong (this "shouldn't happen") the size estimate will be inaccurate and the cache will either be overpurged or underpurged.

The other issue however is with shared caches, since there is no locking during a purge, it's possible for another thread or process to add or remove from the cache (or even purge()), altering the size of the cache during the purge, and this will not be noticed, resulting in either an overpurge or an underpurge.

Neither of these cases will cause a problem for the majority of applications (or even occur in the first place), however you can disable this caching of size() by setting no_cache_cache_size_during_purge to a true value if it does cause you problems.

Please note however that this will mean that size() will need to be called when every key is inspected (not just removed!) for pruning. Read the notes for max_size above as this is likely to have a dramatic performance degredation.

no_overrule_memorycache_size => 0 | 1

By default Cache::CacheFactory::Expiry::Size will attempt a workaround for the problems mentioned in "Memory cache inaccuracies" in the "KNOWN ISSUES AND BUGS" section.

If this behaviour is undesirable, supply a true value to the no_overrule_memorycache_size option.

no_devel_size => 0 | 1

If the above workaround is in effect it will attempt to use Devel::Size if it is available, since this module delves into the internals of perl it can be fragile on perl version changes and you may wish to disable it if this is causing you problems, to do that set the no_devel_size option to a true value.

STORE OPTIONS

There are no per-key options for this policy.

METHODS

You shouldn't need to call any of these methods directly.

$size = $policy->overrule_size( $storage );

This method is used to overrule the usual $storage->size() method when comparing against max_size, it attempts to analyze every object in the cache and sum their memory footprint via $policy->guestimate_size().

By default this is used when trying to workaround issues with the size() method of Cache::MemoryCache.

$size = $policy->guestimate_size( $data );

This method provides a rough (very rough sometimes) estimate of the memory footprint of the data structure $data.

This is used internally by the Cache::MemoryCache workaround.

$boolean = $policy->using_devel_size();

Return true or false depending on whether this policy instance will use Devel::Size in $policy->guestimate_size().

NOTE: this does not imply that $policy->guestimate_size() will itself be being used.

Mostly this is a debug method is so I can write saner regression tests.

$policy->limit_size( $cache, $size );

Called by $cache->limit_size(), this does a one-time prune of the cache to $size size or below.

KNOWN ISSUES AND BUGS

Memory cache inaccuracies

Due to the way that Cache::MemoryCache and Cache::SharedMemoryCache implement the size() method, the values returned do not actually reflect the memory used by a cache entry, in fact it's likely to return a somewhat arbitrary value linear to the number of entries in the cache and independent of the size of the data in the entries.

This means that a 'size' pruning policy applied to storage policies of 'memory' or 'sharedmemory' would not keep the size of the cache under max_size bytes.

So, by default Cache::CacheFactory::Expiry::Size will ignore and overrule the value of Cache::MemoryCache->size() or CacheSharedMemoryCache->size() when checking against max_size and will attempt to use its own guestimate of the memory taken up.

To do this it will make use of Devel::Size if available, or failing that use a very simplistic calculation that should at least be proportional to the size of the data in the cache rather than the number of entries.

Since Devel::Size doesn't appear to be successfully tested on perls of 5.6 vintage or earlier and the bug only effects memory caches, Devel::Size hasn't been made a requirement of this module.

This may all be considered as a bug, or at the least a gotcha.

SEE ALSO

Cache::CacheFactory, Cache::Cache, Cache::SizeAwareFileCache, Cache::SizeAwareCache, Cache::CacheFactory::Object, Cache::CacheFactory::Expiry::Base

AUTHORS

Original author: Sam Graham <libcache-cachefactory-perl BLAHBLAH illusori.co.uk>

Last author: $Author: illusori $

COPYRIGHT

Copyright 2008-2010 Sam Graham.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.