NAME

Thread::Queue::Monitored - monitor a queue for content

SYNOPSIS

use Thread::Queue::Monitored;
my $q = Thread::Queue::Monitored->new( \&monitor );
my ($q,$t) = Thread::Queue::Monitored->new( \&monitor,'exit' );
$q->enqueue( "foo" );
$q->enqueue( undef ); # exit value by default

$t->join; # wait for monitor thread to end

sub monitor {
  warn $_[0] if $_[0] =~ m/something wrong/;
}

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::Monitored is a thread-safe data structure that inherits from Thread::Queue. But unlike the standard Thread::Queue, it starts a single thread that monitors the contents of the queue by taking new values off the queue as they become available.

It can be used for simply logging actions that are placed on the queue. Or only output warnings if a certain value is encountered. Or whatever.

The action performed in the thread, is determined by a name or reference to a subroutine. This subroutine is called for every value obtained from the queue. It should return a true value to indicate that monitoring should continue, and a false value to indicate that monitoring should stop.

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::Monitored->new( \&monitor );
$queue = Thread::Queue::Monitored->new( \&monitor,'exit' );
($queue,$thread) = Thread::Queue::Monitored->new( \&monitor );
($queue,$thread) = Thread::Queue::Monitored->new( \&monitor,'exit' );

The new function creates a new empty queue. It returns the instantiated Thread::Queue::Monitored object in scalar context: in that case, the monitoring thread will be detached and will continue until the exit value is passed on to the queue. Also returns the thread object in list context, which can be used to wait for the thread to be really finished using the join() method.

The first input parameter is a name or reference to a subroutine that will be called to check on each value that is added to the queue. It must be specified. The subroutine is to expect one parameter: the value to check. It is free to do with that value what it wants.

The second (optional) input parameter is the value that will signal that the monitoring of the thread should seize. If it is not specified, the undef value is assumed. To end monitoring the thread, enqueue the same value.

OBJECT METHODS

enqueue

$queue->enqueue( $value1,$value2 );
$queue->enqueue( 'exit' ); # stop monitoring

The enqueue method adds all specified parameters on to the end of the queue. The queue will grow as needed to accommodate the list. If the "exit" value is passed, then the monitoring thread will shut itself down.

CAVEATS

You cannot remove any values from the queue, as that is done by the monitoring thread. Therefore, the methods "dequeue" and "dequeue_nb" are disabled on this object.

AUTHOR

Elizabeth Mattijsen, <liz@dijkmat.nl>.

Please report bugs to <perlbugs@dijkmat.nl>.

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.