NAME
Thread::Conveyor - transport of any data-structure
SYNOPSIS
use Thread::Conveyor;
my $belt = Thread::Conveyor->new;
$belt->put( "foo", ["bar"], {"zoo"} );
my ($foo,$bar,$zoo) = $belt->take;
my ($foo,$bar,$zoo) = $belt->take_dontwait;
my ($foo,$bar,$zoo) = $belt->peek;
my ($foo,$bar,$zoo) = $belt->peek_dontwait;
my $onbelt = $belt->onbelt;DESCRIPTION
*** A note of CAUTION ***
This module only functions on Perl versions 5.8.0 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 or without
threads enabled.
*************************The Thread::Conveyor object is a thread-safe data structure that mimics the behaviour of a conveyor belt. One or more worker threads can put boxes with frozen values and references on one end of the belt to be taken off by one or more worker threads on the other end of the belt to be thawed and returned.
A box may consist of any combination of scalars and references to scalars, arrays (lists) and hashes. Freezing and thawing is currently done with the Storable method, but that may change in the future. Objects and code references are currently not allowed.
CLASS METHODS
new
$belt = Thread::Conveyor->new;The "new" function creates a new empty belt. It returns the instantiated Thread::Conveyor object.
OBJECT METHODS
The following methods operate on the instantiated Thread::Conveyor object.
put
$belt->put( 'string',$scalar,[],{} );The "put" method freezes all the specified parameters together in a box and puts the box on the beginning of the belt.
take
($string,$scalar,$listref,$hashref) = $belt->take;The "take" method waits for a box to become available at the end of the belt, removes that box from the belt, thaws the contents of the box and returns the resulting values and references.
take_dontwait
($string,$scalar,$listref,$hashref) = $belt->take_dontwait;The "take_dontwait" method, like the take method, removes a box from the end of the belt if there is a box waiting at the end of the belt. If there is no box available, then the "take_dontwait" method will return immediately with an empty list. Otherwise the contents of the box will be thawed and the resulting values and references will be returned.
peek
($string,$scalar,$listref,$hashref) = $belt->peek;The "peek" method waits for a box to become availabe at the end of the belt, but does not remove it from the belt like the take method does. It does however thaw the contents and returns the resulting values and references.
peek_dontwait
($string,$scalar,$listref,$hashref) = $belt->peek_dontwait;The "peek_dontwait" method is like the take_dontwait method, but does not remove the box from the belt if there is one available. If there is a box available, then the contents of the box will be thawed and the resulting values and references are returned. An empty list will be returned if there was no box available at the end of the belt.
onbelt
$onbelt = $belt->onbelt;The "onbelt" method returns the number of boxes that are still in the belt.
CAVEATS
Passing unshared values between threads is accomplished by serializing the specified values using Storable when putting a box of values on the belt and removing the values from a box. This allows for great flexibility at the expense of more CPU usage. It also limits what can be passed, as e.g. code references and blessed objects can not be serialized and therefore not be passed.
AUTHOR
Elizabeth Mattijsen, <liz@dijkmat.nl>.
Please report bugs to <perlbugs@dijkmat.nl>.
HISTORY
This module started life as "Thread::Queue::Any" and as a sub-class of Thread::Queue. Using the conveyor belt metaphore seemed more appropriate and therefore the name was changed. To cut the cord with Thread::Queue completely, the belt mechanism was implemented from scratch.
COPYRIGHT
Copyright (c) 2002 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.