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.

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

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.

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 Sam Graham.

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