Digital Mages - Paranoid::IO::FileMultiplexer::Block(3)

Paranoid::IO::FileMultiplexer::Block

Section: User Contributed Perl Documentation (3)
Updated: 2022-03-08
Index

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.

Index

SUBROUTINES/METHODS

new
blockNum
blockSize
minPos
maxPos
allocate
recalibrate
bwrite
bread

DEPENDENCIES

BUGS AND LIMITATIONS

AUTHOR