NAME

       Paranoid::IO::FileMultiplexer::Block - Block-level Allocator/Accessor

VERSION

       $Id: lib/Paranoid/IO/FileMultiplexer/Block.pm, 2.10 2022/03/08 00:01:04 acorliss Exp $

SYNOPSIS

           $obj = Paranoid::IO::FileMultiplexer::Block->new(
                   $filename, $bnum, $bsize);
           $rv  = $obj->allocate;

           $bn   = $obj->blockNum;
           $bs   = $obj->blockSize;
           $minp = $obj->minPos;
           $maxp = $obj->maxPos;

           $bytesWritten = $obj->bwrite($content);
           $bytesWritten = $obj->bwrite($content, $start );
           $bytesWritten = $obj->bwrite($content, $start, $length );
           $bytesWritten = $obj->bwrite($content, $start, $length, $offset );
           $bytesRead    = $obj->bread(\$content);
           $bytesRead    = $obj->bread(\$content, $start, $bytes);
           $bytesRead    = $obj->bread(\$content, undef, $bytes);
           $bytesRead    = $obj->bread(\$content, $start, $bytes);

           $rv = $obj->recalibrate;

DESCRIPTION

       This class is not meant to be used directly, but as part of the Paranoid::IO::FileMultiplexer
       functionality.  It is primarily a base class from which other critical classes are derived.

       This module does presume that whatever file it is being used on has already been opened in the
       appropriate mode, and that the Paranoid::IO flock stack has been enabled.  For the purposes of
       Paranoid::IO::FileMultiplexer, this is done in that class.

SUBROUTINES/METHODS

   new
           $obj = Paranoid::IO::FileMultiplexer::Block->new(
                   $filename, $bnum, $bsize);

       This creates a new instance of a block object.  It requires the filename in order to retrieve the cached
       file handle from Paranoid::IO, the number of the block (using zero-based indexing), and the size of the
       block.  It will block size and the block number to calculate its actual position within the file.

   blockNum
           $bn = $obj->blockNum;

       This method returns the object's assigned block number.

   blockSize
           $bs = $obj->blockSize;

       This method returns the object's assigned block size.

   minPos
           $minp = $obj->minPos;

       This method returns the minimum file position for the block.

   maxPos
           $maxp = $obj->maxPos;

       This method returns the maximum file position for the block.

   allocate
           $rv = $obj->allocate;

       This method attempts to allocate the block on the file system, and returns a boolean indicating its
       success.  This method will fail if you attempt to allocate a block that's already been allocated, or a
       block whose file position is beyond the current end of the file.  In other words, blocks must be
       allocated in sequence.

   recalibrate
           $rv = $obj->recalibrate;

       This method recalculates minimum/maximum file position based on the currently set block size.  This
       should always be called after any change to blockSize.

   bwrite
           $bytesWritten = $obj->bwrite($content);
           $bytesWritten = $obj->bwrite($content, $start );
           $bytesWritten = $obj->bwrite($content, $start, $length );
           $bytesWritten = $obj->bwrite($content, $start, $length, $offset );

       This method writes the passed content to the block, while making sure that the content does not overflow
       the block boundaries.  If the start position of the write is omitted, it writes from the beginning of the
       block.  If the start position is provided, note that this is the position relative to the block, not the
       file.  That means you would specify values from a range of o to (blockSize - 1).

       This method is intentionally designed to allow you to pass more content than will fit inside of a block,
       and yet only write as much as will fit within the block.  The calling code should use the return value to
       figure out what remains to be written in other blocks, as needed.

   bread
           $bytesRead = $obj->bread(\$content);
           $bytesRead = $obj->bread(\$content, $start);
           $bytesRead = $obj->bread(\$content, undef, $bytes);
           $bytesRead = $obj->bread(\$content, $start, $bytes);

       This method reads the content of the block, while making sure that the content read does not go beyond
       the borders of the block.  If the start position of the read is omitted, it reads from the beginning of
       the block.  Like bwrite, this position is relative to the beginning of the block, not the file.

       This method is also intentionally designed to allow you to request more data than can fit within the
       block, yet returning only what the block contains.  The calling code should use the return value to
       figure out what remains to be read from other blocks, as needed.

DEPENDENCIES

       o   Fcntl

       o   Paranoid

       o   Paranoid::Debug

       o   Paranoid::IO

BUGS AND LIMITATIONS

AUTHOR

       Arthur Corliss (corliss@digitalmages.com)

LICENSE AND COPYRIGHT

       This software is free software.  Similar to Perl, you can redistribute it and/or modify it under the
       terms of either:

         a)     the GNU General Public License
                <https://www.gnu.org/licenses/gpl-1.0.html> as published by the
                Free Software Foundation <http://www.fsf.org/>; either version 1
                <https://www.gnu.org/licenses/gpl-1.0.html>, or any later version
                <https://www.gnu.org/licenses/license-list.html#GNUGPL>, or
         b)     the Artistic License 2.0
                <https://opensource.org/licenses/Artistic-2.0>,

       subject to the following additional term:  No trademark rights to "Paranoid" have been or are conveyed
       under any of the above licenses.  However, "Paranoid" may be used fairly to describe this unmodified
       software, in good faith, but not as a trademark.

       (c) 2005 - 2021, Arthur Corliss (corliss@digitalmages.com) (tm) 2008 - 2021, Paranoid Inc.
       (www.paranoid.com)