Parano...Header(3pm)

📦
version 2.10 · 3 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

✨ Parano...Header(3pm) ✨

okay bestie, so this is the Paranoid::IO::FileMultiplexer::Block::StreamHeader page 💖 — it's the Stream Header Block, and it lives in the User Contributed Perl Documentation corner of the Perl 5.38.2 universe, dated 2024-03-07. grab a strawberry 🍓 and let's get into it.

🌸 NAME 🌸

Paranoid::IO::FileMultiplexer::Block::StreamHeader — literally just the Stream Header Block. that's her. that's the girl. 💅

👑 VERSION 👑

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

✨ SYNOPSIS ✨

the whole vibe, verbatim, no cap:

$obj = Paranoid::IO::FileMultiplexer::Block::StreamHeader->new($file,
        $blockNo, $blockSize, $strmName);

$name   = $obj->streamName;
$max    = $obj->maxBATs;
$eos    = $obj->eos;
@bats   = $obj->bats;
$rv     = $obj->full;

$rv     = $obj->writeSig;
$rv     = $obj->readSig;
$rv     = $obj->writeEOS($pos);
$pos    = $obj->readEOS;
$rv     = $obj->validateBlocks;
$rv     = $obj->writeBATs;
$rv     = $obj->readBATs;
$rv     = $obj->addBAT($bn);

🦋 DESCRIPTION 🦋

so, real talk — this class is not meant to be used directly. it's not the main character here, it's the supporting cast 💜. it exists as part of the Paranoid::IO::FileMultiplexer functionality, and it provides all the machinery you need for manipulation of the stream header block. iykyk.

ngl, this module presumes a couple of things about whatever file it's working on:

  • that the file has already been opened in the appropriate mode, aaand
  • that the Paranoid::IO flock stack has been enabled.

for the purposes of Paranoid::IO::FileMultiplexer, both of those things are handled inside that class. so like, not your problem, but you should know 🫶

🎀 SUBROUTINES/METHODS 🎀

🌈 new

$obj = Paranoid::IO::FileMultiplexer::Block::StreamHeader->new($file,
        $blockNo, $blockSize, $strmName);

this creates a new instance of a stream header block object ✨ and it's picky about what you feed it:

  • the filename, so it can go retrieve the cached file handle from Paranoid::IO
  • the block number of the block
  • the size of the block
  • and the name of the stream
⚠️ NOTE: creating an object does not automatically create the file and/or write a signature. you have to do that yourself with the methods below, bestie. the constructor is just standing there. gorgeous, but not doing that. 💀

🌸 streamName

$name = $obj->streamName;

returns the stream name. that's it. that's the whole thing. 😌

💖 maxBATs

$max = $obj->maxBATs;

returns the maximum number of BATs supported by the stream. so many BATs. the limit, fr fr.

🧚 eos

$eos = $obj->eos;

returns the current EOS of the stream 🎀

⚠️ note that this is just the last cached value, which may be out of sync with what's actually sitting in the file. so don't come for me if it's stale. 🙈

⭐ bats

%bats = $obj->bats;

returns an array of BAT block numbers allocated to the stream. yes the synopsis says %bats. no we don't talk about it. the prose says array. we move on. 💅

🍓 full

$rv     = $obj->full;

returns a boolean value denoting whether this stream's array of BAT blocks is at maximum capacity or not. is she full? is she booked and busy? find out. 👑

💜 writeSig

$rv = $obj->writeSig;

writes the stream header signature to disk, and returns a boolean value denoting its success ✅

note that the signature contains:

  • the file format
  • the stream name
  • the current EOS position

it does not include the allocated BAT block numbers. those are a separate situation, okay? 🌸

🎀 readSig

$rv = $obj->readSig;

reads the stream header signature from disk and does basic validation that the info in it is acceptable. it checks that:

  • the stream name matches what's expected, and
  • the block format is correct

if the method call was successful it will update the cached values in the object 🫶

⚠️ note that this is only the signature values, not the BAT block numbers. don't get it twisted. 🙈

🌈 writeEOS

$rv = $obj->writeEOS($pos);

writes the passed stream EOS position to disk, and returns a boolean value denoting success. slay. ✅

🦋 readEOS

$pos = $obj->readEOS;

reads the stream EOS position from disk and returns it 💖

if there are any errors reading or extracting the value, it will return undef. so like, vibe check your return value. 😭

⭐ validateEOS

$rv = $obj->validateEOS;

compares the cached EOS position to what's actually written in the file 🔥

this is useful for determining whether an external process has potentially modified the file. nosy behavior, but make it necessary. 👀

🧚 writeBATs

$rv = $obj->writeBATs;

writes the BAT block numbers to the header block, and returns a boolean denoting success. 💅

💖 readBATs

$rv = $obj->readBATs;

reads the BAT block numbers from the file, and returns a boolean value denoting success. if the read is successful, this will update the cached BATs in the object. bestie is locked in. 🔥

🍓 addBAT

$rv = $obj->addBAT($bn);

does some basic validation of the requested BAT, and if it passes, updates the BAT block number list on the disk ✅

👑 DEPENDENCIES 👑

the whole girl squad, no exceptions:

  • Fcntl
  • Paranoid
  • Paranoid::Debug
  • Paranoid::Data
  • Paranoid::IO
  • Paranoid::IO::FileMultiplexer::Block

💀 BUGS AND LIMITATIONS 💀

literally nothing listed here. empty. void. the silence is deafening. ngl it's giving iconically unbothered. 🎀

🌸 AUTHOR 🌸

Arthur Corliss (corliss@digitalmages.com) — the legend, the blueprint, the author 🫶

this software is free software 💖 similar to Perl, you can redistribute it and/or modify it under the terms of either:

  1. 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
  2. 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. periodt. 💅

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

and that's the page, bestie 🦋 you made it all the way through the Stream Header Block, and honestly? ate. this whole thing came to you courtesy of perl v5.38.2, dated 2024-03-07 — mwah, ily, go read the Paranoid::IO::FileMultiplexer page next 💖✨🎀

📦 where this page comes from