File::Queue(3pm)

💖 NAME 💖

File::Queue — a persistent FIFO queue implemented in pure perl! Like, no XS, no magic, just vibes and filehandles, bestie. It's a User Contributed Perl Documentation page, and honestly? It ate.

---

✨ SYNOPSIS ✨

use strict; # always!
use File::Queue;

my $q = new File::Queue (File => '/var/spool/yourprog/queue');

$q->enq('some flat text1');
$q->enq('some flat text2');
$q->enq('some flat text3');

# Get up to first 10 elements
my $contents = $q->peek(10);

my $elem1 = $q->deq();
my $elem2 = $q->deq();

# empty the queue
$q->reset();

not the use strict; # always! comment, the author is so real for that 😭

---

🦋 DESCRIPTION 🦋

So this module lets you make persistent FIFO queue objects. FIFO = first in, first out, the line at the boba shop, the group chat scrollback, you get it.

File::Queue only handles scalars as queue elements, bestie. That's it. If you wanna work with references, serialize them first! It does not do that part for you.

The module was written with speed in mind, and it is very fast, but it should be used with care — it's giving fast car, fast car needs a responsible driver. Please refer to the CAVEATS section. Do not skip it. I'm serious. 👑

Interface

File::Queue implements a OO interface. The object methods and parameters are described below, because of course they are, we're thorough here.

Methods

File::Queue supports all of the queue-related functions a developer should expect. All of them. The whole roster.

• new() — Instantiates your File::Queue object. Parameters are described in the next sub-section (Parameters), so don't wander off.
• enq() — Enqueues a string element to the queue. That's the put-it-in move. ⭐
• deq() — Dequeues a string element from the queue, and returns the element. If the queue is empty, nothing is returned. That's the take-it-out move.
• peek(n) — Returns an arrayref containing the next n elements in the queue. If the queue size is less than n, all elements are returned. If the queue is empty, an empty arrayref is returned. It's the "look but don't touch" of queue methods 💅
• reset() — Emptys the queue. (Yes, that's the spelling on the page, I'm not touching it. Note it empties the queue, so like, be sure you mean it.)
• close() — Closes the filehandles belonging to the queue object ('.dat' and '.idx'). Bye besties 🫶
• delete() — Deletes the files belonging to the queue object ('.dat' and '.idx'). Straight up gone. No takebacks.

Parameters

There are a number of parameters that can be passed when constructing your File::Queue objects. Parameters are case-insensitive, so go off with your capitalization, it truly doesn't matter.

• File (required) — File::Queue creates two files using this parameter as the base. In the case of the example in the SYNOPSIS, the two files are '/var/spool/yourprog/queue.dat' and '/var/spool/yourprog.idx'.

The '.dat' file holds all of the data, and the '.idx' file holds the byte index (pointer) of the starting point of the first element in the queue. So .dat = the receipts, .idx = the bookmark. 🎀

• Mode (optional) — The file bit mode to be shared by both the '.dat' and '.idx' files. Defaults to '0600'.
• Seperator (optional) — The character or byte sequence that is used to seperate queue elements in the '.dat' file. (Yep, it's spelled Seperator on the page, and it's spelled that way in your code too, so keep it.) It should be something you can guarantee will NEVER appear in your queue data. Defaults to the newline character. Choose wisely, bestie, this is a boundaries thing.
• BlockSize (optional) — This is the size of the byte chunks that are pulled at each iteration when checking for the end of a queued element. Defaults to 64, which will be fine for most cases, but can be tweaked or tuned for your specific case to squeeze out a few extra nanoseconds. A few. Nanoseconds. Obsessed with the precision, honestly. ⚡

---

💀 CAVEATS 💀

Okay so this is the part where I hold your hand. Deep breath. 🌸

This module should never be used in situations where the queue is not expected to become empty.

The '.dat' file is not truncated (emptied) until the queue is empty.

Even the data you've already dequeued remains in the '.dat' file until the queue is empty. Like, you took it out of the queue but it's still sitting in the file. It's still there. It's always been there. 🙈

If you keep enqueueing elements and never FULLY dequeue everything, eventually your disk will fill up! That's not a vibe. That's a 3am incident. Fully dequeue. Periodt. 👑

---

🌈 SEE ALSO 🌈

• Tie::File

---

👑 AUTHOR 👑

Jason Lavold <jlavold [ at ] gmail.com>

---

and that's the whole page, bestie 🫶 this one shipped as perl v5.36.0, dated 2022-10-22, filed under File::Queue(3pm) in User Contributed Perl Documentation. go enqueue something. responsibly. 💖✨