NAME

Cache::CacheFactory::Expiry::Base - base class for Cache::CacheFactory expiry policies.

DESCRIPTION

Cache::CacheFactory::Expiry::Base is the base class for Cache::CacheFactory expiry (pruning and validity) policies.

It provides the base API to adhere to when writing your own custom policies.

METHODS

$policy = Cache::CacheFactory::Expiry::Base->new( $options )

Construct a new expiry policy object with the specified options supplied as a hashref.

What options are avaiable depends on the subclass, you should check the documentation there.

The new() constructor should never need to be called directly, this is handled for you automatically when a policy is set for a cache.

$policy->read_startup_options( $options )

This method is called by the base new() constructor, it allows subclasses to read and process their startup options without having to mess around with redefining the constructor.

$policy->set_object_validity( $key, $object, $param )

$policy->set_object_pruning( $key, $object, $param )

These two methods are invoked when a piece of data is first stored in the cache, just prior to the actual storage, this allows the validity and pruning policies to store any neccessary meta-data against the object for when it is fetched from the cache again.

$key is the key the data is being stored against.

$object is the Cache::CacheFactory::Object wrapper around the data. If you're storing meta-data against the object you will want to look at the $object->set_policy_metadata() method.

$param is a hashref to %additional_param supplied to $cache->set().

$boolean = $policy->should_keep( $cache, $storage, $policytype, $object );

$policy->should_keep() is the core of a expiry policy, it should return a true value if the object should be kept or a false value if the object should be considered invalid or be pruned.

$cache is the parent Cache::CacheFactory, this may or may not be useful to you.

$storage is the storage object instance in case you need it.

$policytype is the policy type, for an expiry policy it will be set to either 'validity' if the validity of an object is being tested, or 'pruning' if we're checking if the object should be pruned. Most policies will only care about the $policytype if they need to access per-policy meta-data on the object.

$object is the Cache::CacheFactory::Object instance for the cache entry being tested. You'll probably want to call some methods on this to make a decision about whether it should be kept or not. $object->get_policy_metadata() may prove useful here if you've stored data during $policy->set_object_validity() or $policy->set_object_pruning().

$boolean = $policy->is_valid( $cache, $storage, $object );

Wrapper function around $policy->should_keep(), this is called when the policy is being used as a validity policy. You shouldn't need to change anything about this method.

$policy->purge( $cache );

This function iterates over each storage policy getting a list of all their keys, then calls $policy->should_keep() with $policytype set to 'pruning', if the returned value is false then the key is removed from that storage policy, if the returned value is true then no change occurs.

If you're writing your own policy you may need to redefine this method if you care about the order in which objects are tested for pruning.

$policy->set_purge_order( $purge_order );

Currently unimplemented, reserved against future development.

$boolean = $policy->pre_purge_hook( $cache );

$policy->post_purge_hook( $cache );

Hooks to allow a subclass to do a little setup or cleanup before or after a purge() is run. If a false value is returned from $policy->pre_purge_hook() then the purge will be aborted for this pruning policy. No other policies will be effected.

It's good practice to include a call to $policy->SUPER::pre_purge_hook() or $policy->SUPER::post_purge_hook() if you're redefining these methods.

$boolean = $policy->pre_purge_per_storage_hook( $cache, $storage );

$policy->post_purge_per_storage_hook( $cache, $storage );

Hooks to allow a subclass to do a little setup or cleanup before or after the purge() against each storage policy. If a false value is returned from $policy->pre_purge_per_storage_hook() then the purge will be aborted for this storage policy for this pruning policy. No other policies will be effected.

It's good practice to include a call to $policy->SUPER::pre_purge_per_storage_hook() or $policy->SUPER::post_purge_per_storage_hook() if you're redefining these methods.

SEE ALSO

Cache::CacheFactory, Cache::Cache, Cache::CacheFactory::Object

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.