Linux Certif

Toute la documentation sur la certification Linux LPI

Thread::Queue::Any.3pm

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

DESCRIPTION

                     *** A note of CAUTION ***
 
  This module only functions on Perl versions 5.8.0-RC3 and later.
  And then only when threads are enabled with -Dusethreads.  It is
  of no use with any version of Perl before 5.8.0-RC3 or without
  threads enabled.
 
                     *************************
 
 

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 "enqueue"s.

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

  Storable (any)
  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 - 2007 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.