NAME

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

SYNOPSIS

use Genezzo::BufCa::BCFile;

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

# register a file
my $fileno = Genezzo::BufCa::BCFile->FileReg(FileName => 'file.dat');

# get back some block 
$bceref = $bc->ReadBlock(filenum  => $fileno,
                         blocknum => $blocknum);
$bce = $$bceref;

DESCRIPTION

The file buffer cache is a simple module designed to form the
basis of a more complicated 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).  See L<Genezzo::BufCa::BufCa>.

Note that this module does not perform space management or allocation 
within the files -- it only reads and writes the blocks.  The caller
is responsible for managing the contents of the file.

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.

BCFileInfoByName Return the file state information.

FileSetHeaderInfoByName Update the datafile header.

FileReg

Register a file with the cache -- returns a file number.  Reregistering
a file should return the same number.

ReadBlock

Takes argument blocknum, which must be a valid block number, and
the argument filenum, which must be a valid file number.  If the
block is in memory it returns the bceref.  If the block is not in
the cache it fetches it from disk into an unused block.  If the 
unused block is dirty, then ReadBlock writes it out first.  
Fails if all blocks are in use.

WriteBlock

Write a block to disk.  Not really necessary -- ReadBlock will
flush some dirty blocks to disk automatically, and Flush
will write all dirty blocks to disk.  

Flush

Write all dirty blocks to disk.

Rollback

Discard all dirty blocks and replace with blocks from disk..

EXPORT

None by default.

LIMITATIONS

Currently requires 2 blocks per open file.

TODO

note that _fileread could just be part of GetInfo

need to move TSExtendFile functionality here if want to overload syswrite with encryption

read_only database support

buffer cache block zero should contain description of buffer cache layout

need a way to free blocks associated with a file that is not currently in use

AUTHOR

Jeffrey I. Cohen, jcohen@genezzo.com

SEE ALSO

perl(1).

Copyright (c) 2003, 2004, 2005 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