Parano...:Block(3pm)

💖 Paranoid::IO::FileMultiplexer::Block 💖

okay so bestie, you just pulled up Parano...:Block(3pm) — that's the perl User Contributed Perl Documentation for section 3pm — and it's er, giving ✨ block-level allocator/accessor ✨. no cap, that's literally the whole vibe of this page. it's the plumbing behind Paranoid::IO::FileMultiplexer, so let's get into it 🫶

---

✨ 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 $

that's version 2.10, dated 2022/03/08 00:01:04, by acorliss, obviously 👑

---

🦋 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 🌈

okay so the tea ☕️: this class is not meant to be used directly. it's part of the Paranoid::IO::FileMultiplexer functionality, and it's primarily a base class — other critical classes get derived from it. it's the momager, not the main character 🎬

this module presumes that whatever file it's being used on has already been opened in the appropriate mode, and that the Paranoid::IO flock stack has been enabled. bestie, that setup is not on you — for the purposes of Paranoid::IO::FileMultiplexer, that's done inside that class. periodt 💅

---

🌸 SUBROUTINES/METHODS 🌸

💜 new

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

this creates a brand-new instance of a block object ✨ it needs three things:

• the filename — so it can retrieve the cached file handle from Paranoid::IO
• the number of the block — using zero-based indexing, iykyk
• the size of the block

and ngl, the source says, word for word: "It will block size and the block number to calculate its actual position within the file." so yeah — it takes the block size and the block number and uses them to calculate its actual position within the file. iconic.

🎀 blockNum

$bn = $obj->blockNum;

hands you back the object's assigned block number. that's it, that's the method 💖

🦋 blockSize

$bs = $obj->blockSize;

returns the object's assigned block size. short and sweet, we love a low-maintenance method.

🌸 minPos

$minp = $obj->minPos;

returns the minimum file position for the block ⭐️

🍓 maxPos

$maxp = $obj->maxPos;

returns the maximum file position for the block 🌈

👑 allocate

$rv = $obj->allocate;

this one attempts to allocate the block on the file system, and returns a boolean telling you whether it slayed or flopped 🫶

⚠️ bestie, listen: this method will fail if you try 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. no skipping ahead, no cutting the line 💀

✨ recalibrate

$rv = $obj->recalibrate;

recalculates the minimum/maximum file position based on the currently set block size. and this is the important part: this should always be called after any change to blockSize. always. no exceptions, no vibes-based shortcuts 🔥

💅 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 the content does not overflow the block boundaries — boundaries are sacred 🚧

if the start position of the write is omitted, it writes from the beginning of the block. and if you do pass a start position, heads up: that position is relative to the block, not the file 🫠 so you'd specify values from a range of o to (blockSize - 1).

and this part is intentional: this method is designed so you can pass more content than will fit inside a block, and it'll only write as much as will fit. so the calling code should use the return value to figure out what remains to be written in other blocks, as needed. it's giving "you handle the rest, bestie" 💁‍♀️

💖 bread

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

reads the content of the block, while making sure 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. and just like bwrite, that position is relative to the beginning of the block, not the file ⭐️

also intentional (icons only): you can request more data than can fit within the block, and it'll return 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. ate and left no crumbs 🍽️

---

🧚 DEPENDENCIES 🧚

• Fcntl
• Paranoid
• Paranoid::Debug
• Paranoid::IO

---

💀 BUGS AND LIMITATIONS 💀

so… the section is here, and it is empty. no bugs listed, no limitations listed. not a single complaint. she simply chose peace 🙈✨

---

🫶 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)

---

and that's the whole page bestie 💖 this gorgeous thing was built by perl v5.38.2, dated 2024-03-07, and you read it all the way to the end — main character energy fr fr 🎀🦋✨