view release on metacpan or  search on metacpan

classdocs/Thread/Queue/Duplex.pod.html  view on Meta::CPAN

on objects implementing <a href="TQDContainer.pod.html">Thread::Queue::TQDContainer</a>.</p>

<p>A <code>mark()</code> method is provided to permit out-of-band information
to be applied to pending requests. A responder may test for marks
via the <code>marked()</code> method prior to <code>respond()</code>ing to a request.
An application may specify a mark value, which the responder can
test for; if no explicit mark value is given, the value 1 is used.</p>

<p><code>cancel()</code> and <code>cancel_all()</code> methods are provided to
explicitly cancel one or more requests, and invoke the
<code>onCancel()</code> method of any <a href="Queueable.pod.html">Thread::Queue::Queueable</a> objects
in the request. Cancelling will result in one of</p>

<ul>
	<li>marking the request as cancelled if
it has not yet been dequeued (note that it cannot be
spliced from the queue due <code>threads::shared</code>'s lack
of support for array splicing)</li>
	<li>removal and discarding of the response from the response map
if the request has already been processed</li>
	<li>if the request is in progress, the responder will
detect the cancellation when it attempts to <code>respond()</code>,
and the response will be discarded</li>
</ul>

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

<p>The constructor also accepts a <code>MaxPending</code> 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.</p>

<p><code>Thread::Queue::Duplex</code> objects encapsulate</p>

<ul>
	<li>a shared array, used as the queue (same as <a href="http://search.cpan.org/perldoc?Thread%3A%3AQueue">Thread::Queue</a>)</li>
	<li>a shared scalar, used to provide unique identifier sequence
numbers</li>
	<li>a shared hash, <i>aka</i> the mapping hash, used to return responses
to enqueued elements, using the generated uniqiue identifier as the hash key</li>
	<li>a listener count, incremented each time <code>listen()</code> is called,
decremented each time <code>ignore()</code> is called, and, if
the &quot;listener required&quot; flag has been set on construction, tested
for each <code>enqueue()</code> call.</li>
</ul>

<p>A normal processing sequence for Thread::Queue::Duplex might be:</p>

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

</pre><h1 id="METHODS">METHODS <a href="#TOP" class="toplink"><img alt="^" src="../../up.gif" /></a></h1>

<p>Refer to the classdocs for summary and detailed method descriptions.</p>

<h1 id="SEE_ALSO">SEE ALSO <a href="#TOP" class="toplink"><img alt="^" src="../../up.gif" /></a></h1>

<p><a href="Queueable.pod.html">Thread::Queue::Queueable</a>, <a href="TQDContainer.pod.html">Thread::Queue::TQDContainer</a>,
<a href="http://search.cpan.org/perldoc?threads">threads</a>, <a href="http://search.cpan.org/perldoc?threads%3A%3Ashared">threads::shared</a>, <a href="http://search.cpan.org/perldoc?Thread%3A%3AQueue">Thread::Queue</a>,
<a href="http://search.cpan.org/perldoc?Thread%3A%3AQueue%3A%3AMultiplex">Thread::Queue::Multiplex</a>, <a href="http://search.cpan.org/perldoc?Thread%3A%3AApartment">Thread::Apartment</a></p>

<h1 id="AUTHOR_COPYRIGHT_amp_LICENSE">AUTHOR, COPYRIGHT, &amp; LICENSE <a href="#TOP" class="toplink"><img alt="^" src="../../up.gif" /></a></h1>

<p>Dean Arnold, Presicient Corp. <a href="#darnold_presicient_com">darnold@presicient.com</a></p>

<p>Copyright(C) 2005,2006, Presicient Corp., USA</p>

<p>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
<a href="http://www.opensource.org/licenses/afl-2.1.php">http://www.opensource.org/licenses/afl-2.1.php</a>.</p>


</div><div class="footer">generated by <a href="http://search.cpan.org/perldoc?Pod%3A%3AProjectDocs">Pod::ProjectDocs</a></div></body>
</html>