Cache man page on Pidora

Man page or keyword search:  
man Server   31170 pages
apropos Keyword Search (all sections)
Output format
Pidora logo
[printable version]

Cache(3)	      User Contributed Perl Documentation	      Cache(3)

NAME
       Cache - the Cache interface

DESCRIPTION
       The Cache modules are designed to assist a developer in persisting data
       for a specified period of time.	Often these modules are used in web
       applications to store data locally to save repeated and redundant
       expensive calls to remote machines or databases.

       The Cache interface is implemented by derived classes that store cached
       data in different manners (such as as files on a filesystem, or in
       memory).

USAGE
       To use the Cache system, a cache implementation must be chosen to suit
       your needs.  The most common is Cache::File, which is suitable for
       sharing data between multiple invocations and even between concurrent
       processes.

       Using a cache is simple.	 Here is some very simple sample code for
       instantiating and using a file system based cache.

	 use Cache::File;

	 my $cache = Cache::File->new( cache_root => '/tmp/cacheroot' );
	 my $customer = $cache->get( $name );

	 unless ($customer) {
	     $customer = get_customer_from_db( $name );
	     $cache->set( $name, $customer, '10 minutes' );
	 }

	 return $customer;

       Of course, far more powerful methods are available for accessing cached
       data.  Also see the TIE INTERFACE below.

METHODS
       my $cache_entry = $c->entry( $key )
	   Return a 'Cache::Entry' object for the given key.  This object can
	   then be used to manipulate the cache entry in various ways.	The
	   key can be any scalar string that will uniquely identify an entry
	   in the cache.

       $c->purge()
	   Remove all expired data from the cache.

       $c->clear()
	   Remove all entries from the cache - regardless of their expiry
	   time.

       my $num = $c->count()
	   Returns the number of entries in the cache.

       my $size = $c->size()
	   Returns the size (in bytes) of the cache.

PROPERTIES
       When a cache is constructed these properties can be supplied as options
       to the new() method.

       default_expires
	   The current default expiry time for new entries into the cache.
	   This property can also be reset at any time.

	    my $time = $c->default_expires();
	    $c->set_default_expires( $expiry );

       removal_strategy
	   The removal strategy object for the cache.  This is used to remove
	   object from the cache in order to maintain the cache size limit.

	   When setting the removal strategy in new(), the name of a strategy
	   package or a blessed strategy object reference should be provided
	   (in the former case an object is constructed by calling the new()
	   method of the named package).

	   The strategies 'Cache::RemovalStrategy::LRU' and
	   'Cache::RemovalStrategy::FIFO' are available by default.

	    my $strategy = $c->removal_strategy();

       size_limit
	   The size limit for the cache.

	    my $limit = $c->size_limit();

       load_callback
	   The load callback for the cache.  This may be set to a function
	   that will get called anytime a 'get' is issued for data that does
	   not exist in the cache.

	    my $limit = $c->load_callback();
	    $c->set_load_callback($callback_func);

       validate_callback
	   The validate callback for the cache.	 This may be set to a function
	   that will get called anytime a 'get' is issued for data that does
	   not exist in the cache.

	    my $limit = $c->validate_callback();
	    $c->set_validate_callback($callback_func);

SHORTCUT METHODS
       These methods all have counterparts in the Cache::Entry package, but
       are provided here as shortcuts.	They all default to just wrappers that
       do '$c->entry($key)->method_name()'.  For documentation, please refer
       to Cache::Entry.

       my $bool = $c->exists( $key )
       $c->set( $key, $data, [ $expiry ] )
       my $data = $c->get( $key )
       my $data = $c->size( $key )
       $c->remove( $key )
       $c->expiry( $key )
       $c->set_expiry( $key, $time )
       $c->handle( $key, [$mode, [$expiry] ] )
       $c->validity( $key )
       $c->set_validity( $key, $data )
       $c->freeze( $key, $data, [ $expiry ] )
       $c->thaw( $key )

TIE INTERFACE
	 tie %hash, 'Cache::File', { cache_root => $tempdir };

	 $hash{'key'} = 'some data';
	 $data = $hash{'key'};

       The Cache classes can be used via the tie interface, as shown in the
       synopsis.  This allows the cache to be accessed via a hash.  All the
       standard methods for accessing the hash are supported , with the
       exception of the 'keys' or 'each' call.

       The tie interface is especially useful with the load_callback to
       automatically populate the hash.

REMOVAL STRATEGY METHODS
       These methods are only for use internally (by concrete Cache
       implementations).

       These methods define the interface by which the removal strategy object
       can manipulate the cache (the Cache is the 'context' of the strategy).
       By default, methods need to be provided to remove the oldest or stalest
       objects in the cache - thus allowing support for the default FIFO and
       LRU removal strategies.	All derived Cache implementations should
       support these methods and may also introduce additional methods (and
       additional removal strategies to match).

       my $size = $c->remove_oldest()
	   Removes the oldest entry in the cache and returns its size.

       my $size = $c->remove_stalest()
	   Removes the 'stalest' (least used) object in the cache and returns
	   its size.

       $c->check_size( $size )
	   This method isn't actually part of the strategy interface, nor does
	   it need to be defined by Cache implementations.  Instead it should
	   be called by implementations whenever the size of the cache
	   increases.  It will take care of checking the size limit and
	   invoking the removal strategy if required.  The size argument
	   should be the new size of the cache.

UTILITY METHODS
       These methods are only for use internally (by concrete Cache
       implementations).

       my $time = Cache::Canonicalize_Expiration_Time($timespec)
	   Converts a timespec as described for Cache::Entry::set_expiry()
	   into a unix time.

SEE ALSO
       Cache::Entry, Cache::File, Cache::RemovalStrategy

DIFFERENCES FROM CACHE::CACHE
       The Cache modules are a total redesign and reimplementation of
       Cache::Cache and thus not directly compatible.  It would be, however,
       quite possible to write a wrapper module that provides an identical
       interface to Cache::Cache.

       The semantics of use are very similar to Cache::Cache, with the
       following exceptions:

       The get/set methods DO NOT serialize complex data types.	 Use
       freeze/thaw instead (but read the notes in Cache::Entry).
       The get_object / set_object methods are not available, but have been
       superseded by the more flexible entry method and Cache::Entry class.
       There is no concept of 'namespace' in the basic cache interface,
       although implementations (eg. Cache::Memory) may choose to provide
       them.  For instance, File::Cache does not provide this - but different
       namespaces can be created by varying cache_root.
       In the current Cache implementations purging is done automatically -
       there is no need to explicitly enable auto purge on get/set.  The
       purging algorithm is no longer implemented in the base Cache class, but
       is left up to the implementations and may thus be implemented in the
       most efficient way for the storage medium.
       Cache::SharedMemory is not yet available.
       Cache::File no longer supports separate masks for entries and
       directories.  It is not a very secure configuration and presents
       numerous issues for cache consistency and is hence depricated.  There
       is still some work to be done to ensure cache consistency between
       accesses by different users.

AUTHOR
	Chris Leishman <chris@leishman.org>
	Based on work by DeWitt Clinton <dewitt@unto.net>

COPYRIGHT
	Copyright (C) 2003-2006 Chris Leishman.	 All Rights Reserved.

       This module is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
       KIND, either expressed or implied. This program is free software; you
       can redistribute or modify it under the same terms as Perl itself.

       $Id: Cache.pm,v 1.7 2006/01/31 15:23:58 caleishm Exp $

POD ERRORS
       Hey! The above document had some coding errors, which are explained
       below:

       Around line 573:
	   You forgot a '=back' before '=head1'

perl v5.14.1			  2006-01-31			      Cache(3)
[top]

List of man pages available for Pidora

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net