Thread...e::Any(3pm)

💖 Thread::Queue::Any 💖

okay bestie, so this page is Thread::Queue::Any, and it lives in the User Contributed Perl Documentation corner of the 3pm universe. it's giving queues, but make them chaotic-good. let's get into it 🫶

---

✨ NAME ✨

Thread::Queue::Any — thread-safe queues for any data-structure 💅

---

✨ SYNOPSIS ✨

use Thread::Queue::Any;
my $q= Thread::Queue::Any->new;
$q->enqueue("foo", ["bar"], {"zoo"});
my ( $foo, $bar, $zoo )= $q->dequeue;
my ( $foo, $bar, $zoo )= $q->dequeue_dontwait;
my ( $iffoo, $ifbar, $ifzoo)= $q->dequeue_keep;
my $left= $q->pending;

# specify class with "freeze" and "thaw" methods
use Thread::Queue::Any serializer => 'Storable';

# specify custom freeze and thaw subroutines
use Thread::Queue::Any freeze => \&solid, thaw => \&liquid;

# thaw hook for subclasses
package Thread::Queue::Any::Foo;
@ISA= 'Thread::Queue::Any';
my $THAW= __PACKAGE__->THAW;

---

✨ VERSION ✨

this documentation describes version 1.17 🎀

---

✨ DESCRIPTION ✨

⚠️ ⚠️ ⚠️ A note of CAUTION ⚠️ ⚠️ ⚠️ This module only functions if threading has been enabled when building Perl, or if the forks module has been installed on an unthreaded Perl. ⚠️ ⚠️ ⚠️ ⚠️ ⚠️ ⚠️ ⚠️ ⚠️ ⚠️ ⚠️ ⚠️ ⚠️ ⚠️

---

so. a queue, the way Thread::Queue::Any does it, is a thread-safe data structure that inherits from Thread::Queue. 🌸 but here's the glow-up: unlike the standard Thread::Queue, you can pass (a reference to) any data structure to the queue. no cap. 💅

aside from the fact that the parameters to enqueue are considered to be a set that needs to be enqueued together, and that dequeue returns all of the parameters that were enqueued together, this module is a drop-in replacement for Thread::Queue in every other aspect. iconic behaviour honestly 👑

any number of threads can safely add elements to the end of the list, or remove elements from the head of the list. that's the whole vibe fr fr 🔥

---

✨ CLASS METHODS ✨

🌟 new

$queue= Thread::Queue::Any->new;

the new function creates a new empty queue. that's it, that's the whole thing. fresh start, main character energy ✨

🌟 THAW

$THAW= $subclass->THAW;

returns the code reference for de-serializing enqueued data. this one is intended to be used by subclasses only, like Thread::Queue::Any::Monitored. iykyk 🧚

---

✨ OBJECT METHODS ✨

🌟 enqueue LIST

$queue->enqueue( 'string', $scalar, [], {} );

the enqueue method adds a reference to all the specified parameters on to the end of the queue. the queue will grow as needed. feed it everything, it does not care 💖

🌟 dequeue

( $string, $scalar, $listref, $hashref )= $queue->dequeue;

$string= $queue->dequeue;          # first only in scalar context

the dequeue method removes a reference from the head of the queue, dereferences it, and returns the resulting values. if the queue is currently empty, dequeue will block the thread until another thread enqueues. so like... it will simply wait for you. patient queen 😭

if called in scalar context, only the first value will be returned. this is only recommended if enqueue is always only called with one parameter. ⭐

🌟 dequeue_dontwait

( $string, $scalar, $listref, $hashref )= $queue->dequeue_dontwait;

$string= $queue->dequeue_dontwait; # first only in scalar context

the dequeue_dontwait method, like the dequeue method, removes a reference from the head of the queue, dereferences it, and returns the resulting values. unlike dequeue, though, dequeue_dontwait won't wait if the queue is empty — instead it returns an empty list if the queue is empty. it has places to be 💅

for compatibility with Thread::Queue, the name dequeue_nb is available as a synonym for this method. two names, one icon 🌈

if called in scalar context, only the first value will be returned. this is only recommended if enqueue is always only called with one parameter. ⭐

🌟 dequeue_keep

( $string, $scalar, $listref, $hashref )= $queue->dequeue_keep;

$string= $queue->dequeue_keep;     # first only in scalar context

the dequeue_keep method, like the dequeue_dontwait method, takes a reference from the head of the queue, dereferences it, and returns the resulting values. unlike dequeue_dontwait, though, dequeue_keep won't remove the set from the queue. 👀 so you can use it to test if the next set to be returned from the queue with dequeue or dequeue_dontwait will have a specific value. it's a peek, not a steal 🍓

if called in scalar context, only the first value will be returned. this is only recommended if enqueue is always only called with one parameter. ⭐

🌟 pending

$pending= $queue->pending;

the pending method returns the number of items still in the queue. a little headcount, if you will 💜

---

✨ USING ANOTHER SERIALIZER ✨

passing unshared values between threads is accomplished by serializing the specified values when enqueuing and de-serializing the queued value on enqueuing. this allows for great flexibility at the expense of more CPU usage 😭 it also limits what can be passed, as e.g. code references can not be serialized with the default serializer and therefore not be passed. sorry code refs, you're not invited to this party 🙈

by default, the Storable module is used to serialize data. if you want to use a different serializer, you can specify this when you load this module with the serializer parameter:

use Thread::Queue::Any serializer => 'Thread::Serialize';

the value of the parameter is the name of the class that will provide a freeze and thaw subroutine. it will be automatically loaded if specified. ✨

if you happen to have subroutines in another module with a different name, you can also specify the freeze and thaw parameter with a code reference of the subroutine to be called. so the above example could also be specified as:

use Thread::Serialize;
use Thread::Queue::Any
  freeze => \&Thread::Serialize::freeze,
  thaw   => \&Thread::Serialize::thaw,
;

---

✨ REQUIRED MODULES ✨

• Test::More (0.88)
• Thread::Queue (any)

---

✨ INSTALLATION ✨

this distribution contains two versions of the code: one maintenance version for versions of perl < 5.014 (known as 'maint'), and the version currently in development (known as 'blead'). the standard build for your perl version is:

perl Makefile.PL
make
make test
make install

this will try to test and install the blead version of the code. if the Perl version does not support the blead version, then the running of the Makefile.PL will fail. 😭 in such a case, one can force the installing of the maint version of the code by doing:

perl Makefile.PL maint

alternately, if you want automatic selection behavior, you can set the AUTO_SELECT_MAINT_OR_BLEAD environment variable to a true value. on Unix-like systems like so:

AUTO_SELECT_MAINT_OR_BLEAD=1 perl Makefile.PL

if your perl does not support the blead version of the code, then it will automatically install the maint version of the code. it just knows. it handles it. 🫶

please note that any additional parameters will simply be passed on to the underlying Makefile.PL processing. 🎀

---

✨ AUTHOR ✨

Elizabeth Mattijsen, <liz@dijkmat.nl>.

maintained by LNATION <email@lnation.org>

please report bugs to <email@lnation.org>. 💌

---

✨ COPYRIGHT ✨

Copyright (c) 2002, 2003, 2007, 2012 Elizabeth Mattijsen <liz@dijkmat.nl>. 2025 LNATION <email@lnation.org> All rights reserved. this program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

✨ SEE ALSO ✨

threads, threads::shared, Thread::Queue, Storable. go read them bestie, they're all part of the lore 📚

---

and that's the whole page!! 💖 this was perl v5.40.1, dated 2025-04-20, and it's Thread::Queue::Any(3pm) — thanks for reading, ily, go enqueue something 🦋✨👑