NAME

Genezzo::BufCa::BufCa.pm - A simple in-memory buffer cache for a
single process, without locking.    

SYNOPSIS

use Genezzo::BufCa::BufCa;

# get a buffer cache
my $bc = Genezzo::BufCa::BufCa->new(blocksize => 10, numblocks => 5);

# find a free block
my $free_arr =  $bc->GetFree();

# get the block number and a reference to a Buffer Cache Element
my $blocknum = shift (@{$free_arr});
my $bceref   = shift (@{$free_arr});

# obtain the actual Buffer Cache Element
my $bce = $$bceref;

# can later use the block number to revisit this Buffer Cache Element
.
.
.
# get back the same block 
$bceref = $bc->ReadBlock(blocknum => $blocknum);
$bce = $$bceref;

DESCRIPTION

The in-memory buffer cache is a simple module designed to form the
basis of a more complicated, file-based, multi-process buffer cache
with locking.  The buffer cache contains a number of Buffer Cache
Elements (BCEs), a special wrapper class for simple byte buffers
(blocks).  The BCE has two callback functions or closures of note:

pin

A block is pinned as long as the bceref (returned via GetFree or
ReadBlock) is in scope.  BufCa uses a scalar tie class to unpin the
block when the bceref is garbage collected.  The basic pin function
acts as a form of advisory locking, and could be upgraded to a true
locking mechanism.

dirty

a block is marked as dirty if it is modified.  

FUNCTIONS

new

Takes arguments blocksize (required, in bytes), numblocks (10 by
default).  Returns a new buffer cache of the specified number of
blocks of size blocksize.

GetFree

Returns an array @free = (block number, bceref).  The bceref and its
associated blocknumber are for a block that is currently not in use.
Note that the block might be dirty.  Also, GetFree is not a space
allocator -- it only indicates that a block is not in use.

ReadBlock

Takes argument blocknum, which must be a valid block number.  Returns
a bceref

WriteBlock - unused for in-memory cache

EXPORT

None by default.

AUTHOR

Jeffrey I. Cohen, jcohen@genezzo.com

SEE ALSO

perl(1).

Copyright (c) 2003, 2004 Jeffrey I Cohen. All rights reserved.

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

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Address bug reports and comments to: jcohen@genezzo.com