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.16.

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.