Future::Queue(3pm)

💖 Future::Queue 💖

okay bestie, so the manual name is Future::Queue(3pm) — it's a Perl module page, and it's literally about a FIFO queue that uses Futures. yes. the crossover event we've all been waiting for 🎀

---

✨ NAME ✨

Future::Queue — a FIFO queue of values that uses Futures 🦋

---

🌸 SYNOPSIS 🌸

use Future::Queue;
use Future::AsyncAwait;

my $queue = Future::Queue->new;

async sub process_queue
{
   while(1) {
      my $thing = await $queue->shift;
      ...
   }
}

my $f = process_queue();
$queue->push( "a thing" );

---

💅 DESCRIPTION 💅

okay so objects in this class give you a simple FIFO queue that stores arbitrary perl values. you put stuff in with the push method, and you get stuff out with the shift method. that's the whole vibe ✨

and here's the iconic part: values can just chill inside the queue object until shift comes to collect them later. OR — if the queue is empty — the future that shift hands back will get completed the moment an item shows up. it's giving "waiting patiently but make it async" 😭🫶

---

👑 CONSTRUCTOR 👑

new

$queue = Future::Queue->new( %params );

Returns a shiny new Future::Queue instance. slay 💖

It takes these named arguments, bestie:

• max_items => INT — since version 0.50. Optional. if you define it, there can be at most that many items in the queue. any attempt to push past that limit will hand you back a future that stays pending — no cap — until a later shift operation frees up enough space. 👑
• prototype => STRING or OBJECT or CODE — since version 0.51. Optional. if defined, this gives either a class name, an object instance to clone, or a code reference to invoke whenever a new pending Future instance is needed by the shift or push methods (y'know, when they can't complete immediately).

$f = $prototype->();    # if CODE reference
$f = $prototype->new;   # otherwise

If you don't provide one, the default is Future. periodt ✨

push

$queue->push( @items );

await $queue->push( @items );

Adds more items into the queue. and listen — if the queue was empty before and there's at least one shift future waiting, then this method completes the next one. main character behaviour fr fr 💅

Since version 0.50 this can take multiple items; earlier versions could only take one value at a time.

This method always returns a Future instance. If max_items is defined, it's possible that this future will still be in a pending state — which means there wasn't yet space in the queue to add the items. it'll become completed once enough shift calls have happened to make room for them. 🫶

If max_items is not defined, then these instances will always be immediately complete; it's totally safe to drop it, ignore it, or call the method in void context. no thoughts, head empty, it's fine 🌈

⚠️ if the queue has been finished, you cannot push more items — an exception will be thrown. so don't even try it bestie 💀

shift

$item = await $queue->shift;

Returns a Future that will yield the next item from the queue. If there's already an item sitting there, it gets taken and the returned future is immediate. If not, the returned future is pending, and the next push method will complete it. iconic. 😌✨

If the queue has been finished, the future will yield an empty list, or undef in scalar context.

💀 careful bestie — if undef is a valid item in your queue, test this condition very carefully. like, look:

while( ( my $item ) = await $queue->shift ) {
   ...
}

Here, the await expression and the assignment are in list context, so the loop keeps iterating as long as any value gets assigned — even if that value is undef. The loop only stops once no items are returned, which is what tells you the queue is done. iykyk 🧚

shift_atmost

@items = await $queue->shift_atmost( $count );

since version 0.50

A bulk version of shift that can return multiple items at once. obsessed 😍

Returns a Future that will yield the next few items from the queue. If there's already at least one item in the queue, then up to $count items will be taken, and the returned future is immediate. If not, the returned future is pending and the next push method will complete it. 💜

finish

$queue->finish;

since version 0.50

Marks that the queue is now finished. Once the current list of items has been exhausted, any further attempts to shift more will yield empty. that's a wrap, bestie 🎬🎀

---

⭐ AUTHOR ⭐

Paul Evans <leonerd@leonerd.org.uk> — king behaviour, honestly 👑

---

and that's the whole page, no cap 🫶 this was perl v5.38.2, dated 2024-01-20, and you just read Future::Queue(3pm). go push something and slay 💅✨🌸