view release on metacpan or  search on metacpan

lib/Thread/Queue/Duplex.pod  view on Meta::CPAN

removal and discarding of the response from the response map
if the request has already been processed

=item *

if the request is in progress, the responder will
detect the cancellation when it attempts to C<respond()>,
and the response will be discarded

=back

C<listen()> and C<ignore()> methods are provided so that
server-side threads can register/unregister as listeners
on the queue; the constructor accepts a "ListenerRequired"
attribute argument. If set, then any C<enqueue()>
operation will fail and return undef if there are no
registered listeners. This feature provides some safeguard
against "stuck" requestor threads when the responder(s)
have shutdown for some reason. In addition, a C<wait_for_listener()>
method is provided to permit an initiating thread to wait
until another thread registers as a listener.

The constructor also accepts a C<MaxPending> attribute
that specifies the maximum number of requests that may
be pending in the queue before the operation will block.
Note that responses are not counted in this limit.

C<Thread::Queue::Duplex> objects encapsulate

=over 4

=item *

a shared array, used as the queue (same as L<Thread::Queue>)

=item *

a shared scalar, used to provide unique identifier sequence
numbers

=item *

a shared hash, I<aka> the mapping hash, used to return responses
to enqueued elements, using the generated uniqiue identifier as the hash key

=item *

a listener count, incremented each time C<listen()> is called,
decremented each time C<ignore()> is called, and, if
the "listener required" flag has been set on construction, tested
for each C<enqueue()> call.

=back

A normal processing sequence for Thread::Queue::Duplex might be:

	#
	#	Thread A (the client):
	#
		...marshal parameters for a coroutine...
		my $id = $q->enqueue('function_name', \@paramlist);
		my $results = $q->dequeue_response($id);
		...process $results...
	#
	#	Thread B (the server):
	#
		while (1) {
			my $call = $q->dequeue;
			my ($id, $func, @params) = @$call;
			$q->respond($id, $self->$func(@params));
		}

=head1 METHODS

Refer to the classdocs for summary and detailed method descriptions.

=head1 SEE ALSO

L<Thread::Queue::Queueable>, L<Thread::Queue::TQDContainer>,
L<threads>, L<threads::shared>, L<Thread::Queue>,
L<Thread::Queue::Multiplex>, L<Thread::Apartment>

=head1 AUTHOR, COPYRIGHT, & LICENSE

Dean Arnold, Presicient Corp. L<darnold@presicient.com>

Copyright(C) 2005,2006, Presicient Corp., USA

Licensed under the Academic Free License version 2.1, as specified in the
License.txt file included in this software package, or at OpenSource.org
L<http://www.opensource.org/licenses/afl-2.1.php>.

=cut