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)