view release on metacpan or  search on metacpan

lib/Cache/RamDisk.pm  view on Meta::CPAN

On application shutdown:

   cache_remove ('/tmp/rd');


=head1 DESCRIPTION

I<Note: 'rd' is from now on in this document an abbreviation for 'ramdisk' or 'RAM Disk' or however you prefer
to write or exclaim that herewith specified thing.>

Cache::RamDisk provides multi-process applications with a means of sharing Perl objects between the
processes while trying to avoid the inconveniences inherent to other IPC tools:

1. Message queues are extremely fast, but extremely limited too.

2. Shared memory is perhaps even faster, but it came out for me to be an at least hairy problem
trying to store several references all in one segment.

3. Sockets are reliable, but require a second communication endpoint and yet another server process.

But a file is a file is a file.

The package collects as much ramdisks to a bundle as possible and necessary to hold the required user space,
depending on the respective parameters under which the system's individual kernel had been compiled.
The system user and group who owns the cache can be specified for the whole rd bunch, say cache.


=head2 Cache Types

The package provides three ways of cacheing policy. The desired type can be submitted to the individual
object constructor with one of the following values:

=head3 CACHE_LRU

Forces the accessing object methods to treat the cache under B<L>ast B<R>ecently B<U>sed aspects: an existent
object will be delivered, and the respective index entry moves to the top. Values from the 'Keys' reference
in the latest call to C<install()> define the B<maximum number of objects> for the respective key. If the index
list is full, its last line will be C<pop()>ped and the new entry C<unshift()>ed.

=head3 CACHE_TIMED

All accesses from this object to the cache treat the value for each cache key as B<maximum age in seconds>
that cache objects belonging to the key are allowed to reach. "Stale" objects will not be delivered,
but removed instead. (The decision whether to deliver or remove happens on every C<get()> request. There
may a thread be born some day.)

=head3 CACHE_DEFAULT

A fallback policy by which you may use parts of your cache as a convenient substitute for SysV shared
memory. Values set for the cache keys are ignored - which means that you will have
to invalidate objects on this type of cache "by hand". Indexes are being kept up to date by simple
C<unshift()>s and C<splice()>s. B<Note: the invalidate() method is not part of v0.1.2!>


=head1 REQUIRES

Perl B<5.6.1> on a Linux/ Unix System containing the following binaries:

   chown, mkdir, mke2fs, mount, umount

The package uses these Perl modules available from CPAN:

   IPC::Shareable
   IPC::SysV
   Filesys::Df
   Filesys::Statvfs
   File::stat
   Fcntl
   Symbol
   Class::Struct
   POSIX


=head1 EXPORTS

   CACHE_DEFAULT, CACHE_LRU, CACHE_TIMED

=head1 METHODS

=head2 Class Methods

=head3 Cache::RamDisk->new ( $basepath [, $type [, $shmemkey]])

Creates a new class instance that will act on the cache denoted by C<$basepath>. If no C<$type> has
been requested, C<CACHE_DEFAULT> is assumed. Please note that, although it is possible to access one cache
with several types of instances at the same time, it is not intended to create one instance of
several types. Do not try to perform bitwise operations on C<$type>, as their results will all lead to a
C<CACHE_DEFAULT> cache. Returns undef when called as a class method, or when the 'Base' parameter is
missing. The C<$shmemkey> argument is optional, but it becomes a vital necessity, if you want to access
a cache that has been created with another than the default key. See L<Cache::RamDisk::Functions> for
details.

From this and from what can be read under L<CACHE TYPES> follows: it is up to the programmer's
responsibility how the cache will act. You will always have to have in mind which keys on the cache
you want to be treated like what in one application. If you don't always stick to the same type of
cache for one key, you will most likely mostly never get a predictable result, but see far below.


=head2 Object Methods

All of the following methods return the C<undef> value when called with faulty arguments, unless
no runtime error prevents them from returning at all. ("faulty" means that they return the undef value
also when called as class methods.)

=head3 $c-E<gt>errstr

If an error has ocurred in the current B<instance>, holds the message.

=head3 $c-E<gt>get ( $href )

Get one or more objects from the current cache. The values in C<$href> may be scalars or arrayrefs.
There may obviously be more than one key in the argument hash. Thus C<get()> is a means to retrieve
a bunch of objects at one request. Returns a reference to a hash of hashrefs.

Examples:

   $c->get( { 'fie' => 12345 } )  returns   { 'fie' => { '12345' => $a_reference }}

   $c->get( { 'fie' => [12345, 67890],