Dicop::Cache - cache items with timeout and limit

	use Dicop::Cache;

	my $cache = Dicop::Cache->new( timeout => 3600, items => 12);

	$cache->put (foo => 'bar');
        sleep(2);
        for ($i = 0; $i < 14; $i++)
          {
	  $cache->put ( $i => 'fooo');
          }
	print $cache->items(),"\n";		# will be 12

	my $cache = Dicop::Cache->new( timeout => 2*3600);	# no limit

	my $stats = $cache->statistics();

	print "Hits: $stats->{hits} Misses: $stats->{misses}\n";

perl5.005, Exporter

Exports nothing per default.

This module keeps a cache of things. The cache has a timeout, anything that is older will be deleted. In addition it can also have a limit on how many items it can hold.

Old items will be automatically purged from the cache when you call get(), put(), items() or purge().

Create a new cache object. Parameters are as follows:

	timeout		in seconds, time to live for a cache entry
	limit		how many items to keep 

	$cache->clean();

Clean all entries from the cache, making it an empty cache. It also resets all the statistics.

	my $item = $cache->get( $key );

Return the item with the key $key from the cache, or undef if it is not in. See also get_time and touch.

get() does NOT touch an item. If you want to always purge the least accessed items, do:

	my $item = $cache->get( $key );
	$cache->touch( $key );			# make youngest

	$cache->touch( $key );
	$item = $cache->touch( $key );

Update the time on an item to now (making it expire later), returns the item or undef.

	$cache->get_time( $key );

Return the time of insertion (or the latest touch()) of the item with the key $key from the cache, or undef if the item is not in the cache. See also get and touch.

	$cache->put( $key => $value );

Insert the item with the value $value and the key $key into the cache. If the cache has entries too old or too much entries (exceeding the limit), then it will be cleaned of these.

	$key = $cache->oldest();

Return key of oldest item in cache. To get the actually oldest item, see get_oldest. If there are no items in the cache yet, will return undef.

	$elder_one = $cache->get_oldest();

Returns the oldest item in the cache. If the cache is empty, returns undef.

Do NOT use the following:

	$elder_one = $cache->get( $cache->oldest() );	# WRONG!

Because the item that $cache->oldest() returns might expire before the $cache->get( ) can retrieve it.

	$cache->timeout(3600);
	print $cache->timeout(3600),"\n";

Return and/or set the timeout value of the entries. Any entry older than this will be purged from the cache.

	$cache->limit(12);		# set to 12
	print $cache->limit(),"\n";	# print it
	$cache->limit(undef);		# disable limit

Return and/or set the limit aka the maximum allowed number of entrie.

Purge all old items, then return number of items left in cache.

Purges all old items, and keep not more than limit() items in cache. Returns number of items left.

	my $stats = $cache->statistics();

Returns a hash ref. The hash contains the following keys:

	hits	 times a get() hit a cached item and returned it
	misses	 times a get() did not find a cached item
	puts	 how many times was put() called
	gets	 how many times was get() called (misses+hits)

inserting

Inserting more items than $limit at the same time will not properly keep the oldest (granularity is one second).

(c) Bundesamt fuer Sicherheit in der Informationstechnik 1998-2008

DiCoP is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation.

See http://www.bsi.de/ for more information.