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;VERSION
This documentation describes version 0.15.
DESCRIPTION
*** A note of CAUTION ***
This module only functions on threaded perl or an unthreaded perl
with the "forks" module installed.
Please also note that this documentation describes the "maint" version
of this code. This version is essentially frozen. Please use a 5.14
or higher version of perl for the "blead" version of this code.
*************************A queue, as implemented by Thread::Queue::Any is a thread-safe data structure that inherits from Thread::Queue. But unlike the standard Thread::Queue, you can pass (a reference to) any data structure to the queue.
Apart 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.
Any number of threads can safely add elements to the end of the list, or remove elements from the head of the list. (Queues don't permit adding or removing elements from the middle of the list).
CLASS METHODS
new
$queue= Thread::Queue::Any->new;The new function creates a new empty queue.
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.
dequeue
( $string, $scalar, $listref, $hashref )= $queue->dequeue;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.
dequeue_dontwait
( $string, $scalar, $listref, $hashref )= $queue->dequeue_dontwait;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 returning an empty list if the queue is empty.
For compatibility with Thread::Queue, the name "dequeue_nb" is available as a synonym for this method.
dequeue_keep
( $string, $scalar, $listref, $hashref )= $queue->dequeue_keep;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, the dequeue_keep won't remove the set from the queue. It can therefore be used to test if the next set to be returned from the queue with dequeue or dequeue_dontwait will have a specific value.
pending
$pending= $queue->pending;The pending method returns the number of items still in the queue.
REQUIRED MODULES
Thread::Queue (any)CAVEATS
Passing unshared values between threads is accomplished by serializing the specified values using Storable when enqueuing and de-serializing the queued value on dequeuing. 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 and therefore not be passed.
AUTHOR
Elizabeth Mattijsen, <liz@dijkmat.nl>.
Please report bugs to <perlbugs@dijkmat.nl>.
COPYRIGHT
Copyright (c) 2002, 2003, 2007, 2012 Elizabeth Mattijsen <liz@dijkmat.nl>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.