NAME

Dicop::Cache - cache items with timeout and limit

SYNOPSIS

        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";
        

REQUIRES

perl5.005, Exporter

EXPORTS

Exports nothing per default.

DESCRIPTION

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

METHODS

new

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 

clean

        $cache->clean();

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

get

        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

touch

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

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

get_time

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

put

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

oldest

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

get_oldest

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

timeout

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

limit

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

items

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

purge

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

statistics

        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)

BUGS

inserting

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

AUTHOR

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

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.

cpanm Dicop::Base

perl -MCPAN -e shell
install Dicop::Base