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

 None by default.

AUTHOR

 Jeffrey I. Cohen, jcohen@genezzo.com

SEE ALSO

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., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

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

For more information, please visit the Genezzo homepage at <http://www.genezzo.com>