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.14.
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.
*************************
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.
CLASS METHODS¶
new¶
$queue= Thread::Queue::Any->new;
The "new" function creates a new empty queue.
THAW¶
$THAW= $subclass->THAW;
Return the code reference for de-serializing enqueued data. Intended to be used
by subclasses only, such as Thread::Queue::Any::Monitored.
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;
$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
"enqueue"s.
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
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.
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, 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.
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.
USING ANOTHER SERIALIZER¶
Passing unshared values between threads is accomplished by serializing the
specified values when enqueuing and de-serializing the queued value on
equeuing. 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.
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.
Please note that any additional parameters will simply be passed on to the
underlying Makefile.PL processing.
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.
SEE ALSO¶
threads, threads::shared, Thread::Queue, Storable.