NAME

IPC::Cache - a perl module that implements an object storage space where data is persisted across process boundaries

SYNOPSIS

use IPC::Cache;

# create a cache in the specified namespace, where objects # will expire in one day my $cache = new Cache( { namespace => 'MyCache', expires_in => 86400 } );

# store a value in the cache (will expire in one day)

$cache->set("key1", "value1");

# retrieve a value from the cache

$cache->get("key1");

# store a value that expires in one hour

$cache->set("key2", "value2", 3600);

# clear this cache's contents

$cache->clear();

# delete all namespaces from shared memory

IPC::Cache::CLEAR();

DESCRIPTION

IPC::Cache is used to persist data across processes via shared memory.

TYPICAL USAGE

A typical scenario for this would be a mod_perl or perl CGI application. In a multi-tier architecture, it is likely that a trip from the front-end to the database is the most expensive operation, and that data may not change frequently. Using this module will help keep that data on the front-end. Consider the following usage in a mod_perl application, where a mod_perl application serves out images that are retrieved from a database. Those images change infrequently, but we want to check them once an hour, just in case. my $cache = new Cache( { namespace => 'Images', expires_in => 3600 } ); my $image = $imageCache->get("the_requested_image");

if (!$image) { 

    # $image = [expensive database call to get the image]
    $cache->set("the_requested_image", $image);

}

That bit of code, executed in any instance of the mod_perl/httpd process will first try the shared memory cache, and only perform the expensive database call if the image has not been fetched before, has timed out, or the cache has been cleared.

METHODS

new(\%options)

Creates a new instance of the cache object. The constructor takes a reference to an options hash which can contain any or all of the following:

$options{namespace}
Namespaces provide isolation between objects. Each cache refers to one and only one namespace. Multiple caches can refer to the same namespace, however. While specifying a namespace is not required, it is recommended so as not to have data collide.
$options{expires_in}
If the "expires_in" option is set, all objects in this cache will be cleared in that number of seconds. It can be overridden on a per-object basis. If expires_in is not set, the objects will never expire unless explicitly set.
$options{cache_key}
The "cache_key" is used to determine the underlying shared memory segment to use. In typical usage, leaving this unset and relying on namespaces alone will be more than adequate.
set($identifier, $object, $expires_in)

Adds an object to the cache. set takes the following parameters:

$identifier
The key the refers to this object.
$object
The object to be stored.
$expires_in (optional)
The object will be cleared from the cache in this number of seconds. Overrides the default expire_in for the cache.
get($identifier)

Retrieves an object from the cache. get takes the following parameter:

$identifier
The key referring to the object to be retrieved.
clear()
Removes all objects from this cache.
purge()
Removes all objects that have expired
IPC::Cache::CLEAR($cache_key)

Removes this cache and all the associated namespaces from shared memory. CLEAR takes the following parameter:

$cache_key (optional)
Specifies the shared memory segment to be cleared. Needed only if a cache was created in a non-standard shared memory segment.
IPC::Cache::PURGE($cache_key)

Removes all objects in all namespaces that have expired. PURGE takes the following parameter:

$cache_key (optional)
Specifies the shared memory segment to be purged. Needed only if a cache was created in a non-standard shared memory segment.
IPC::Cache::SIZE($cache_key)

Roughly estimates the amount of memory in use. SIZE takes the following parameter:

$cache_key (optional)
Specifies the shared memory segment to be examined. Needed only if a cache was created in a non-standard shared memory segment.

BUGS

AUTHOR

DeWitt Clinton <dclinton@eziba.com>