<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>Thread::Apartment</title>
<link rel="stylesheet" type="text/css" href="../podstyle.css" /><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
</head>
<body>
<div class="box">
<h1 class="t1">Thread::Apartment</h1>
<table>
<tr>
<td class="label">Description</td>
<td class="cell">Apartment threading wrapper for Perl objects</td>
</tr>
</table>
</div>
<div class="path">
<a href="../index.html">Thread::Apartment</a> > Package Manuals >
Thread-Apartment
</div>
<div>
<a href="../Thread/Apartment.html">Classdocs</a>
</div>
<div class="pod">
<!-- INDEX START -->
<h3 id="TOP">Index</h3>
<ul>
<li><a href="#NAME">NAME</a></li>
<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#DESCRIPTION">DESCRIPTION</a><br />
<ul>
<li><a href="#Glossary">Glossary</a></li>
</ul>
</li>
<li><a href="#METHODS">METHODS</a><br />
<ul>
<li><a href="#Application_Notes_and_Restrictions">Application Notes and Restrictions</a><br />
<ul>
<li><a href="#Closures_must_be_passed_from_TAS_obj">Closures must be passed from TAS objects.</a></li>
<li><a href="#Passing_filehandles">Passing filehandles</a></li>
<li><a href="#Cannot_Provide_Proxied_Access_to_Mem">Cannot Provide Proxied Access to Members of Tied Objects</a></li>
<li><a href="#Proxied_operator_overloading_not_sup">Proxied operator overloading not supported</a></li>
<li><a href="#Proxied_lvalue_methods_not_supported">Proxied lvalue methods not supported</a></li>
<li><a href="#AUTOLOADing_in_Apartment_Threaded_Pa">AUTOLOADing in Apartment Threaded Packages</a></li>
<li><a href="#Use_code_self_gt_isa_code_not_code_r">Use <code>$self->isa()</code>, not <code>ref $self</code></a></li>
<li><a href="#Subclassing_Thread_Apartment_Server">Subclassing Thread::Apartment::Server</a></li>
<li><a href="#I_O_Bound_Classes">I/O Bound Classes</a></li>
<li><a href="#Classes_with_Control_Loops">Classes with Control Loops</a></li>
<li><a href="#Subclassing_Thread_Apartment_Client">Subclassing Thread::Apartment::Client</a></li>
<li><a href="#Installing_POPO_s">Installing POPO's</a></li>
<li><a href="#Externally_Created_Threads_Must_Run_">Externally Created Threads Must Run <code>Thread::Apartment::run()</code></a></li>
<li><a href="#Errors_Returned_as_code_undef_code_w">Errors Returned as <code>undef</code>, with Error Text in <code>$@</code></a></li>
<li><a href="#Object_returning_Methods">Object-returning Methods</a></li>
<li><a href="#Cyclic_Object_Method_Dependencies">Cyclic Object/Method Dependencies</a></li>
<li><a href="#Unexpected_TAC_AUTOLOADs_for_Indirec">Unexpected TAC AUTOLOADs for Indirect Object References</a></li>
<li><a href="#Passing_Invoking_Closures_Between_T_">Passing/Invoking Closures Between T::A Objects</a><br />
<ul>
<li><a href="#Processing_of_CODEREF_Closures">Processing of CODEREF Closures</a></li>
<li><a href="#Processing_of_TACl_Closures">Processing of TACl Closures</a></li>
<li><a href="#Closures_as_Return_Values">Closures as Return Values</a></li>
<li><a href="#Limitations">Limitations</a></li>
</ul>
</li>
<li><a href="#Asynchronous_Method_Calls">Asynchronous Method Calls</a></li>
</ul>
</li>
<li><a href="#Best_Practices">Best Practices</a><br />
<ul>
<li><a href="#Allocate_threads_and_TQDs_early">Allocate threads and TQDs early</a></li>
<li><a href="#Use_T_A_set_single_threaded_for_debu">Use T::A::set_single_threaded() for debugging</a></li>
<li><a href="#Wrap_Filehandles_With_Access_Discipl">Wrap Filehandles With Access Discipline Objects</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#PREREQUISITES">PREREQUISITES</a></li>
<li><a href="#CHANGE_HISTORY">CHANGE HISTORY</a><br />
<ul>
<li>
<ul>
<li><a href="#Release_0_50">Release 0.50</a></li>
<li><a href="#Release_0_10">Release 0.10</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#TO_DO">TO DO</a><br />
<ul>
<li>
<ul>
<li><a href="#Filehandle_marshalling_support">Filehandle marshalling support</a></li>
<li><a href="#Operator_overloading">Operator overloading</a></li>
<li><a href="#lvalue_methods">lvalue methods</a></li>
<li><a href="#Provide_multiprocess_distributed_imp">Provide multiprocess/distributed implementation</a></li>
<li><a href="#Implement_AptSimplex_AptUrgent_metho">Implement AptSimplex, AptUrgent method attributes</a></li>
<li><a href="#Support_CLONE_SKIP">Support CLONE_SKIP()</a></li>
<li><a href="#Implement_as_C_XS_or_Inline_C">Implement as C/XS or Inline::C</a></li>
<li><a href="#Implement_T_A_wrappers_for_commonly_">Implement T::A wrappers for commonly useful modules</a></li>
<li><a href="#Support_for_a_href_http_search_cpan_">Support for <a href="http://search.cpan.org/perldoc?Thread%3A%3AQueue%3A%3AMultiplex">Thread::Queue::Multiplex</a></a></li>
<li><a href="#Better_Support_for_DESTROY">Better Support for DESTROY</a></li>
<li><a href="#Add_a_Thread_Apartment_Rendezvous_cl">Add a Thread::Apartment::Rendezvous class</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#SEE_ALSO">SEE ALSO</a></li>
<li><a href="#AUTHOR_amp_COPYRIGHT">AUTHOR & COPYRIGHT</a></li>
</ul>
<hr />
<!-- INDEX END -->
<h1 id="NAME">NAME <a href="#TOP" class="toplink"><img alt="^" src="../up.gif" /></a></h1>
<p>Thread::Apartment - Apartment threading wrapper for Perl objects</p>
<h1 id="SYNOPSIS">SYNOPSIS <a href="#TOP" class="toplink"><img alt="^" src="../up.gif" /></a></h1>
<pre> package MyClass;
use Thread::Apartment::Server;
use base qw(Thread::Apartment::Server);
sub new {
#
# the usual constructor
#
}
#
# mark some methods as simplex
#
sub get_simplex_methods {
return { 'bar' => 1 };
}
#
# mark some methods as urgent
#
sub get_urgent_methods {
return { 'bingo' => 1 };
}
sub foo {
#
# do something
#
}
sub bar {
#
# do something else
#
}
sub bingo {
print "BINGO!\n";
}
1;
#
# create pool of 20 apartment threads
#
Thread::Apartment->create_pool(AptPoolSize => 20);
my $apt = Thread::Apartment->new(
AptClass => 'MyClass', # class to install in apartment
AptTimeout => 10, # timeout secs for TQD responses
AptRequire => { # classes to require into the thread
'This::Class' => '1.234',
'That::Class' => '0.02'
},
AptParams => \@params_for_MyClass) || die $@;
my $result = $apt->foo(@params);
die $@ unless $result;
#
# bar is simplex
#
$apt->bar(@params);
</pre><h1 id="DESCRIPTION">DESCRIPTION <a href="#TOP" class="toplink"><img alt="^" src="../up.gif" /></a></h1>
<p>Thread::Apartment provides an apartment threading wrapper for Perl
classes. "Apartment threading" is a method for isolating an object
(or object hierarchy) in its own thread, and providing external
interfaces via lightweight client proxy objects. This approach
is especially valuable in the Perl threads environment, which
doesn't provide a direct means of passing complex, nested structure
objects between threads, and for non-threadsafe legacy object
architectures, e.g., <a href="http://search.cpan.org/perldoc?Tk">Perl/Tk</a>.</p>
<p>By using lightweight client proxy objects that implement the
<a href="http://search.cpan.org/perldoc?Thread%3A%3AQueue%3A%3AQueueable">Thread::Queue::Queueable</a> interface, with <a href="http://search.cpan.org/perldoc?Thread%3A%3AQueue%3A%3ADuplex">Thread::Queue::Duplex</a>
objects as the communication channel between client proxies and
apartment threads (<i>or between threads in general</i>), a more thread-friendly
OO environment is provided, <i>ala</i> Java, i.e., the ability to pass
arbitrary objects between arbitrary threads.</p>
<p>Thread::Apartment is a fundamental component of the PSiCHE framework
(<a href="http://www.presicient.com/psiche">http://www.presicient.com/psiche</a>).</p>
<h2 id="Glossary">Glossary</h2>
<dl>
<dt><strong>TQD - </strong><a href="http://search.cpan.org/perldoc?Thread%3A%3AQueue%3A%3ADuplex">Thread::Queue::Duplex</a></dt>
<dd><p>The communications channel used between apartment threads.</p></dd>
<dt><strong>TQQ - </strong><a href="http://search.cpan.org/perldoc?Thread%3A%3AQueue%3A%3AQueueable">Thread::Queue::Queueable</a></dt>
<dd><p>Abstract class that specifies the <strong>curse()</strong> and <strong>redeem()</strong> methods
used for marshalling objects across a TQD.</p></dd>
<dt><strong>POPO - Plain Old Perl Object</strong></dt>
<dd><p>An object that does <strong>not</strong> implement Thread::Apartment::Server</p></dd>
<dt><strong>thread governor</strong></dt>
<dd><p>The primary control loop of an apartment thread. Usually provided by the
<code>Thread::Apartment</code>'s internal <code>_run()</code> method, it is responsible for managing the
installation of an instance into the apartment thread, unmarshalling method
calls from the TQD, invoking the calls on the TAS object(s), and
marshalling and returning results to the caller (via the TAC). The default
governor may be overridden by either providing an externally created
thread to the T::A::new() factory method, or by implementing a
Thread::Apartment::MuxServer object (see <strong>TAMS</strong> below).</p></dd>
<dt><strong>T::A - Thread::Apartment object</strong></dt>
<dd><p>A Singleton class that acts as a factory for Thread::Apartment::Client
objects, and creates or installs instances of their Thread::Apartment::Server
counterparts in a thread.</p></dd>
<dt><strong>TAS - Thread::Apartment::Server</strong></dt>
<dd><p>Base class to be subclassed by objects which will run
as proxied objects in their own thread. Also acts as a container
class for POPO's.</p></dd>
<dt><strong>TAC - Thread::Apartment::Client</strong></dt>
<dd><p>A <a href="http://search.cpan.org/perldoc?threads%3A%3Ashared">threads::shared</a> object that provides the proxy for Thread::Apartment::Server
objects, and can be shared/passed between threads.</p></dd>
<dt><strong>TACo - Thread::Apartment::Container</strong></dt>
<dd><p>A lightweight, non-shared proxy container object that resides in the same thread as its
<code>install()</code>ed (<strong>not</strong> created) TAS object. It implements TQQ such that,
when passed to a proxy object for another thread, it will pass its proxied object's
TAC to the other thread. TACo's permit <code>install()</code>'ed objects to be manipulated
by the application within the installed thread before turning over control of the
thread to the apartment threaded object.</p></dd>
<dt><strong>TAES - Thread::Apartment::EventServer</strong></dt>
<dd><p>Subclass of Thread::Apartment::Server to provide
a <strong>poll()</strong> method that is called by the thread governor at regular intervals
to detect and process class-specific events, e.g., polling I/O handles.</p></dd>
<dt><strong>TAMS - Thread::Apartment::MuxServer</strong></dt>
<dd><p>Subclass of Thread::Apartment::Server that inverts the
control scheme for classes which must implement their own thread governor,
e.g., <a href="http://search.cpan.org/perldoc?Tk%3A%3AThreaded">Tk::Threaded</a>.</p></dd>
<dt><strong>TACl - Thread::Apartment::Closure</strong></dt>
<dd><p>A simple class used to contain and marshal closures between apartment
threads.</p></dd>
</dl>
<h1 id="METHODS">METHODS <a href="#TOP" class="toplink"><img alt="^" src="../up.gif" /></a></h1>
<p>Refer to the included classdocs for summary and detailed method
descriptions.</p>
<h2 id="Application_Notes_and_Restrictions">Application Notes and Restrictions</h2>
<h3 id="Closures_must_be_passed_from_TAS_obj">Closures must be passed from TAS objects.</h3>
<p>In the general case, closures cannot be passed between threads. Hence,
a special mapping scheme is used to proxy a closure originating
in one TAS but passed to another TAS. As such, closures originating
outside a TAS cannot be passed to T::A object.</p>
<p>If your application needs to pass a closure to a T::A object from the
main processing flow (e.g., to supply a closure to <a href="http://search.cpan.org/perldoc?Tk%3A%3AThreaded">Tk::Threaded</a>),
you'll need to create a class and create or install an instance
of it in an apartment thread.</p>
<h3 id="Passing_filehandles">Passing filehandles</h3>
<p>Filehandles (<i>aka GLOBs</i>) cannot be passed between ithreads; hence, any
objects which contain GLOB's (e.g., IO::Socket) also cannot readily be passed.
The recommended method for passing filehandles between threads
is to pass the fileno() and reconstruct the filehandle in
the receiving thread (via either <a href="http://search.cpan.org/perldoc?IO%3A%3AHandle">IO::Handle</a>::fdopen()
or open(FH, "&$fileno")).</p>
<p>Despite best efforts, no consistent solution for
marshalling and esp. unmarshalling filehandles - while preserving
their access modes and <a href="http://search.cpan.org/perldoc?PerlIO">PerlIO</a> layers - could be found. As of Perl 5.8.6,
there appear to be bugs in open() and binmode() regarding mixing
fileno open()'s and layers, and Win32 doesn't
appear to have any means of recovering access modes from an existing
filehandle.</p>
<p>Therefore, applications are responsible for providing their own
mechanisms for marshalling filehandles between threads.</p>
<h3 id="Cannot_Provide_Proxied_Access_to_Mem">Cannot Provide Proxied Access to Members of Tied Objects</h3>
<p>Since TAC is itself a threads::shared object, and threads::shared
objects cannot be tied, it is not possible to proxy the tied
<code>STORE</code>, <code>FETCH</code>, etc. methods. Note that this does <strong>not</strong>
preclude using a tied object in an T::A, but the resulting
TAC will not be able to access the tied elements of the proxied
object.</p>
<p>It may be possible to create a non-threads::shared subclass
of TAC to support the tied capability; refer to <a href="http://search.cpan.org/perldoc?DBIx%3A%3AThreaded">DBIx::Threaded</a>
for hints on how to support tied objects.</p>
<h3 id="Proxied_operator_overloading_not_sup">Proxied operator overloading not supported</h3>
<p>Operator overloading is not currently supported.
A future version of T::A may provide a means to
proxy overloaded operators, <i>ala</i> proxied closures.</p>
<h3 id="Proxied_lvalue_methods_not_supported">Proxied lvalue methods not supported</h3>
<p>Due to the inability to capture the actual assignment
event associated with lvalue subs, it is not possible for
the proxy TAC to safely pass the assigned value back to the
proxied object.</p>
<p>However, clever subclasses of TAC - and associated TAS subclasses -
may overcome this limitation by creating lvalue'd subs in the TAC,
and permitting the TAS to directly reference the TAC's members
<i>(since the TAC is threads::shared, it members are available to
the TAS thread)</i>.
Implementors of such subclasses are urged to be mindful of the
probable locking requirements, and the inability to determine
the precise instance when an lvalue assignment occurs.</p>
<h3 id="AUTOLOADing_in_Apartment_Threaded_Pa">AUTOLOADing in Apartment Threaded Packages</h3>
<p>In order to minimize proxy overhead, when an object is
installed into an apartment thread, the object's <code>@ISA</code>
hierarchy (as reported by <a href="http://search.cpan.org/perldoc?Class%3A%3AISA">Class::ISA</a>::self_and_super_path),
and the list of available public methods (as reported by
<a href="http://search.cpan.org/perldoc?Class%3A%3AInspector">Class::Inspector</a>::methods()) are exported to the client
proxy objects, so that <code>isa()</code> and <code>can()</code> will execute locally
without the overhead of a request/response exchange over
the TQD. As a result, the installed object should explicitly declare
and/or implement all public methods.</p>
<p>However, classes which need to rely on AUTOLOADing can specify that
in a number of ways:</p>
<ul>
<li>override TAS's <code>introspect()</code> method by including the AUTOLOAD method
name in the returned list of declared methods</li>
<li>override TAS's <code>introspect()</code> method and call T::A's <code>set_autoload</code>
method to force AUTOLOAD support for all objects within the apartment.</li>
<li>specify a true value for T::A::new/install() <code>AptAutoload</code> parameter
(useful for creating apartment threaded POPO's which need AUTOLOADing)</li>
</ul>
<p>When an undeclared public (i.e., no leading underscore) method is
invoked, if AUTOLOADing has been enabled by any of these methods,
the object's TAC will pass the method call
to the TAS, which can AUTOLOAD if needed. Note that undeclared methods
are always executed as duplex, non-urgent methods, and that
<code>can()</code> method calls will be passed to the TAS if an undeclared
method is referenced</p>
<h3 id="Use_code_self_gt_isa_code_not_code_r">Use <code>$self->isa()</code>, not <code>ref $self</code></h3>
<p>Due to the exported <code>@ISA</code> described above, using the
<code>ref</code> operator on the client stub objects will report
a TAC or TACo object, rather than
the proxied object. TAC overrides
the <code>UNIVERSAL::isa()</code> method to test the exported <code>@ISA</code>
hierarchy.</p>
<h3 id="Subclassing_Thread_Apartment_Server">Subclassing Thread::Apartment::Server</h3>
<p>TAS provides implementations of several abstract methods which may
be overridden in subclasses. Refer
to the Thread::Apartment::Server classdocs for method details.</p>
<h3 id="I_O_Bound_Classes">I/O Bound Classes</h3>
<p>Classes which detect/trap I/O (or other async) events should inherit from
TAES and provide an implementation of its <code>poll()</code> method, in order to interleave
the apartment thread's TQD <code>dequeue()</code> calls and the detection of
internal events. E.g., a network socket monitor which calls
<code>select()</code> to detect socket events
would implement the <code>select()</code> call with some small timeout inside its
<code>poll()</code> implementation. <code>Thread::Apartment::run()</code> detects the
installation of a TAES object, and will use TQD's <code>dequeue_nb()</code> method,
rather than <code>dequeue()</code>, to check for incoming method calls, and, if none
are available, will call the object's <code>poll()</code> method to permit the object
to field any events.</p>
<h3 id="Classes_with_Control_Loops">Classes with Control Loops</h3>
<p>Classes which encapsulate their own control loops (e.g., <a href="http://search.cpan.org/perldoc?Tk">Perl/Tk</a>)
should inherit from TAMS and frequently call <code>Thread::Apartment::MuxServer::handle_method_requests()</code>
to check for and process any external proxied method calls.
T::A detects the installation of a TAMS object, and cedes control to the TAMS's
<code>run()</code> method when the internal T::A::_run() method is called.</p>
<h3 id="Subclassing_Thread_Apartment_Client">Subclassing Thread::Apartment::Client</h3>
<p>When a TAS based class is used, the class may override the <code>create_client()</code>
method to manufacture its own TAC. By subclassing TAC, the implementation
can provide optimizations of TAC behavior, e.g., providing thread local
accessor/mutator methods for static scalar values, or for <a href="http://search.cpan.org/perldoc?threads%3A%3Ashared">threads::shared</a>
scalar, array, or hash refs, in order to avoid the overhead of making a
proxied method call.</p>
<p>Refer to the Thread::Apartment::Client classdocs for detailed descriptions
of its methods.</p>
<h3 id="Installing_POPO_s">Installing POPO's</h3>
<p>In order to provide the greatest possible flexibility, T::A supports
installing <i>Plain Old Perl Objects</i> aka <i>POPOs</i>. POPOs do <strong>not</strong>
implement the TAS class, and thus can be nearly any existing class definition,
with the following limitations:</p>
<ul>
<li><strong>Constructor must be</strong> <code>new()</code></li>
<li><strong>All methods must be declared, i.e., no AUTOLOAD support</strong></li>
<li><strong>All methods are called as duplex, non-urgent</strong></li>
<li><strong>Methods that return</strong> <code>undef</code> <strong>are assumed to be returning an error,
with any error text in</strong> <code>$@</code></li>
</ul>
<h3 id="Externally_Created_Threads_Must_Run_">Externally Created Threads Must Run <code>Thread::Apartment::run()</code></h3>
<p>In the event an application wants to supply threads to the
Thread::Apartment constructor (e.g., from a pre-created thread pool),
the threads should use the <code>Thread::Apartment::run()</code> method, e.g.,</p>
<pre> #
# create our backchannel
#
my $cmdq = Thread::Queue::Duplex(ListenerRequired => 1);
$cmdq->listen();
#
# ...some more code...
#
# create our thread pool:
# start the threads first, then retrieve their
# TQDs; this minimizes the context the started
# threads inherit
#
my %tqds;
my @my_threads;
push @my_threads, threads->create(\&Thread::Apartment::run, $cmdq)
foreach (1..$poolsize);
#
# now get their TQDs: the thread
# posts them to the backchannel, along
# with the thread ID from which it came
#
foreach (1..$poolsize) {
my $resp = $cmdq->dequeue();
$tqds->{$resp->[0]} = $resp->[1]
if $resp;
}
</pre><h3 id="Errors_Returned_as_code_undef_code_w">Errors Returned as <code>undef</code>, with Error Text in <code>$@</code></h3>
<p>T::A assumes that any non-simplex method that returns
<code>undef</code> has an error, and the error message is available in
<code>$@</code> (as for <code>eval{}</code> operations). An application specific
adapter class may be required to adapt existing classes to
this error reporting behavior.</p>
<h3 id="Object_returning_Methods">Object-returning Methods</h3>
<p>When an object reference is returned from a T::A managed object,
T::A checks if the object is a TQQ object (i.e., it implements
<code>curse()</code> and <code>redeem()</code> methods). If it is, then the
object is marshalled to the TQD as usual. Otherwise,
T::A assumes the returned object is part of an
object hierarchy to be executed within its current apartment
thread (<i>aka "Zone Threading"</i>), and will</p>
<ul>
<li>add it to its object heirarchy map</li>
<li>assign it a unique ID</li>
<li>generate a TAC for it, using the current T::A's TQD</li>
<li>return the TAC instance, rather than the object itself</li>
</ul>
<p>Note that, in the event the object has previously been mapped
in the hierarchy, the existing TAC instance for the object will
be reused.</p>
<p>T::A (<i>via TAS::marshalResults()</i>) does
<strong>not</strong> do a deep inspection of returned values to
detect instances of non-TAC objects.</p>
<p>If an application returns objects within a returned data structure,
it will need to provide an appropriate subclass to implement the needed
marshal/unmarshal methods.</p>
<h3 id="Cyclic_Object_Method_Dependencies">Cyclic Object/Method Dependencies</h3>
<p>If TAS object A calls method1() on TAS object B,
which in turn calls method2() on TAS A, then the
associated apartment threads will deadlock (A is waiting
for a response from B, while B is waiting on a response
from A). Such problems may be avoided by any of</p>
<ul>
<li>declaring A's method2() as simplex. However, this option is
<strong>not</strong> viable if <code>method2()</code> returns a value, and deadlock
may still result if object A starts another blocking proxied call
after the call to <code>method2()</code>.</li>
<li>using an asynchronous method call with a completion closure
(see <a href="#Asynchronous_Method_Calls">Asynchronous Method Calls</a>). However, this approach
is a bit non-obvious, and may require object A's logic to
be structure to inject some wait states for the results
of method2().</li>
<li>using re-entrancy on object A's thread while calling
object B. Re-entrancy can be set in any of the following ways:</li>
</ul>
<dl>
<dt>setting the <strong>AptReentrant</strong> constructor parameter</dt>
<dt>calling <code>T::A::set_reentrancy(1)</code></dt>
<dt>using the <code>ta_reentrant_</code> method prefix for method1()</dt>
</dl>
<p>The re-entrancy approach causes the TAC
for object B to use a special <code>Thread::Apartment::run_wait()</code> method
which will field any incoming proxy method requests for object A
at the same time as it waits for the results from the call
to <code>method2</code>. The class-method version of <a href="http://search.cpan.org/perldoc?Thread%3A%3AQueue%3A%3ADuplex">Thread::Queue::Duplex</a>::wait()
is used to wait on both the local proxied object's TQD, as well as
waiting on the response to the specific method request sent
to object B's TQD.</p>
<p>Note that using the <code>ta_reentrant_</code> method prefix has a transient effect,
i.e., it only applies to the single method call; the other 2
approaches will persist the re-entrant behavior for all proxied method
calls from all objects within the thread, including closure calls,
until <code>Thread::Apartment::set_reentrancy(0)</code> is called to disable
re-entrancy.</p>
<p>Finally, note that re-entrancy should be used with caution,
as it could lead to inadvertantly deep recursions; process-wide performance
degradation (due to the lock signalling required); and unexpected
object states compared to the non-threaded, sequentially executed
equivalent.</p>
<h3 id="Unexpected_TAC_AUTOLOADs_for_Indirec">Unexpected TAC AUTOLOADs for Indirect Object References</h3>
<p>If an object is indirectly referenced via a hash, e.g.,
<code>$objmap->{'MyObject'}->someMethod();</code>, TAC's AUTOLOAD may
get a DESTROY method reference, rather than the expected
'someMethod' value <i>(the reasons for this are not yet clear...)</i>.
As a result, it may be neccesary to dereference the object into
a lexical variable to invoke the method, e.g.,</p>
<pre> my $temp = $objmap->{'MyObject'};
$temp->someMethod();
</pre><p>Further investigation is needed to determine the reason for this
behavior.</p>
<h3 id="Passing_Invoking_Closures_Between_T_">Passing/Invoking Closures Between T::A Objects</h3>
<p>Managing closures in T::A relies on ithread's isolation of class
variables between threads, i.e., assume SomeClass declares</p>
<pre> package SomeClass;
our $variable;
</pre><p>Further assume that SomeClass is loaded into 2 different threads.
Then modifying <code>$SomeClass::variable</code> in thread A <strong>does not</strong>
effect the current value of <code>$SomeClass::variable</code> in thread B.</p>
<p>Hence, T::A declares the following non-threads::shared class variables:</p>
<dl>
<dt><strong>%closure_map</strong></dt>
<dd><p>A map of <strong>closure IDs</strong> to their actual CODEREF. A closure ID is used
to lookup the closure to be called when the recipient of the
closure eventually invokes it.</p></dd>
<dt><strong>$next_closure_id</strong></dt>
<dd><p>A generator for unique integer closure ID's. Note that the 2 least significant
bits of a closure ID indicate the simplex (bit 0) and/or urgent (bit 1)
property of the closure.</p></dd>
<dt><strong>$closure_signature</strong></dt>
<dd><p>Set to the timestamp when an object was installed in the T::A thread. Provides
a sanity check for recycled T::A threads; when closure calls are made on objects which
have been evicted, the signature will not match, and hence the call is not
made, and an error is returned.</p></dd>
<dt><strong>$closure_tac</strong></dt>
<dd><p>A TAC used to proxy all closures generated within the thread.</p></dd>
</dl>
<p>When a new root object is installed into an apartment thread, the <code>%closure_map</code>
and <code>$next_closure_id</code> variables are reset, and <code>$closure_signature</code> is
set to the current timestamp.</p>
<p>2 methods for passing closures are supported: either directly as CODEREF's,
or by creating Thread::Apartment::Closure <i>aka</i> TACl instances. The latter
method permits the closure generator to specify the simplex/and or urgent
properties of a closure. When specified as a simple CODEREF, the closure
recipient will always assume the closure is duplex (i.e., will
wait for a returned result) and non-urgent.</p>
<p>The following methods are provided to support creating TACl's explicitly:</p>
<dl>
<dt><strong>$self->new_tacl</strong>(<i>CODEREF</i>)</dt>
<dd><p>Generates a regular TACl object. CODEREF will be invoked
in duplex, non-urgent mode.</p></dd>
<dt><strong>$self->new_simplex_tacl</strong>(<i>CODEREF</i>)</dt>
<dd><p>Generates a simplex TACl object. CODEREF will be invoked in
simplex, non-urgent mode.</p></dd>
<dt><strong>$self->new_urgent_tacl</strong>(<i>CODEREF</i>)</dt>
<dd><p>Generates an urgent TACl object. CODEREF will be invoked in
duplex, non-urgent mode.</p></dd>
<dt><strong>$self->new_urgent_simplex_tacl</strong>(<i>CODEREF</i>)</dt>
<dd><p>Generates a simplex, urgent TACl object. CODEREF will be invoked in
simplex, urgent mode.</p></dd>
</dl>
<p>E.g.,</p>
<pre> #
# regular CODEREF: $recvr will wait for the closure to complete
#
$recvr->someMethod(-command => sub { print "in a closure"; });
#
# TACl: $recvr will not wait for the closure to complete
#
$recvr->someMethod(-command => $self->new_simplex_tacl(sub { print "in a closure"; }));
</pre><p>Simplex closures may be useful in situations where 2 apartments may "ping-pong"
closure calls on each other, in order to avoid deadlock. They may also be
useful to expedite processing when no returned values are needed.</p>
<p>Default closure call behavior can be modified via either</p>
<ul>
<li>Setting the <code>T::A::new/install(AptClosureCalls)</code> parameter to 'Simplex', 'Urgent',
or both, e.g.<pre> my $tac = Thread::Apartment->new(...
AptClosureCalls => [ 'Simplex', 'Urgent'],
...);
</pre>
<br /><br />(useful for specifying behavior for POPO's).</li>
<li>Overriding the default TAS <code>introspect</code> method to call <code>T::A::set_closure_behavior()</code>
with a bitmask of the <code>TA_SIMPLEX</code> and/or <code>TA_URGENT</code> values.</li>
</ul>
<p>The following acronyms are used in the following detailed discussion:</p>
<dl>
<dt>CRTAC - Closure Recipient TAC</dt>
<dd><p>TAC for the object to which the closure is being passed.</p></dd>
<dt>CRTAS - Closure Recipient TAS</dt>
<dd><p>TAS for the object to which the closure is being passed.</p></dd>
<dt>CGTAC - Closure Generator TAC</dt>
<dd><p>TAC for the object which generated the closure.</p></dd>
<dt>CGTAS - Closure Generator TAC</dt>
<dd><p>TAS for the object which generated the closure.</p></dd>
</dl>
<h4 id="Processing_of_CODEREF_Closures">Processing of CODEREF Closures</h4>
<p>When a CGTAS object passes a CODEREF to a CRTAC, the CRTAC's marshalling
logic will detect the CODEREF (within the T::A::Common::marshal method).
At that point in time, the CRTAC is executing within the CGTAS's
thread, and hence, any assignment to the thread's Thread::Apartment class
variables will be private to that thread.</p>
<dl>
<dt>1</dt>
<dd><p>The CRTAC calls <strong>Thread::Apartment::register_closure</strong>, passing the CODEREF.</p></dd>
<dt>2</dt>
<dd><p><code>register_closure</code> generates a new duplex, non-urgent closure ID,
maps the CODEREF into its %closure_map, and returns the $closure_siganture,
the generated ID, and the CGTAC.</p></dd>
<dt>3</dt>
<dd><p>The CRTAC then marshals the signature, ID, and CGTAC as a
TACl object in the marshalled stream.</p></dd>
<dt>4</dt>
<dd><p>When the CRTAS detects the TACl object in the request stream,
it converts the object into a local closure call on the CGTAC:</p></dd>
<dd><pre> sub { $cgtac->ta_invoke_closure($signature, $id, @_); }
</pre></dd> <dd><p>which the CRTAS can then apply in the proxied method call as a regular
CODEREF.</p></dd>
<dt>5</dt>
<dd><p>When the CRTAS eventually calls the closure, the invoke_closure()
method is marshalled as usual by the CGTAC (<i>possibly including the marshalling of
proxied closures from the CRTAS</i>),
except that the simplex and urgent bits if <code>$id</code> are checked to determine
if the closure requires any special queueing (as for a simplex or urgent
method).</p></dd>
<dt>6</dt>
<dd><p>The CGTAS recognizes the <code>ta_invoke_closure()</code> method, and looks
up the closure in its map. If the $id does not exist, or the signature
does not equal the current $closure_signature, an error is returned
(assuming a duplex closure call). Otherwise, the mapped closure is called, along
with any passed parameters, as for a normal method call, and any results are
likewise returned as for a normal method call.</p></dd>
</dl>
<h4 id="Processing_of_TACl_Closures">Processing of TACl Closures</h4>
<p>When a CGTAS wishes to apply simplex or urgent properties to a closure,
it must create a complete TACl object. The TACl object behaves much like
the CRTAC for the CODEREF case: it calls class-level methods to allocate an ID,
applies the simplex and/or urgent bits to the ID, then maps the closure into
the thread's map, and installs the local TAC into the TACl.</p>
<p>When the CRTAC detects the TACl while marshalling the method call, it
simply invokes TACL's curse() method to marshal the signature, ID, and CGTAC.</p>
<p>The remainder of the closure processing is identical to the CODREF case.</p>
<h4 id="Closures_as_Return_Values">Closures as Return Values</h4>
<p>Thus far, closures have been discussed solely as method arguments; however,
closures may also be return values. In such cases, the CRTAC
will marshall the closure as for the CODEREF or TACl cases described above,
and they'll be recovered in the CRTAS when the return values are unmarshalled.
The invokation of the closures remains the same.</p>
<h4 id="Limitations">Limitations</h4>
<p>In its current implementation, the marshalling/unmarshalling process
does not detect closures deep within structures passed between threads.
In such cases, the <a href="http://search.cpan.org/perldoc?Storable">Storable</a> package used to marshal/unmarshal complex
non-threads::shared structures between threads will throw an error.</p>
<p>If an application needs to pass such complex structure between threads,
it will need to provide its own TAC subclasses, with appropriate marshalling
logic to map the closures.</p>
<h3 id="Asynchronous_Method_Calls">Asynchronous Method Calls</h3>
<p>As an additional means of avoiding deadlock situations as described
above, and to simplify execution of concurrent operations,
T::A provides support for asynchronous method calls on duplex
methods. Two async method call mechanisms are supported:</p>
<ul>
<li>If a called method is prefixed with <strong>"ta_async_"</strong>, and a closure
is provided as the first argument for the method call, then the TAC
will return immediately without any results (as for simplex calls), and
the closure will be invoked when the called object returns its results,
using the previously described proxied closure mechanism. The closure will
be called with the method's returned results. E.g.,<pre> #
# in the caller
#
$tac->ta_async_some_method(
sub {
$self->recv_async_results('some_method_1', @_);
}
);
#
# later in the caller
#
sub recv_async_results {
my $self = shift;
my $unique_id = shift;
#
# some_method()'s returned results are in @_
#
}
</pre>
<br /><br />Note the unique indentifier included in the closure definition;
while not required, including some unique ID may be a best practice
when attempting to handle multiple async closure invokations.</li>
<li>Using Thread::Apartment's <code>start()</code> and <code>rendezvous()</code> methods to
start a method or closure, and then later wait for it (and possibly
other pending requests). E.g.,<pre> #
# using the full class qualifier
#
Thread::Apartment->start($tac1)->someMethod(@params);
#
# using the exported method name
#
use Thread::Apartment qw(start rendezvous);
start($tac2)->otherMethod(@params);
my $closuretac = start($closure)->(@params);
...some other code...
my @tacs = rendezvous();
#
# then check the returned results
#
print "Got ", $_->get_pending_results(), "\n"
foreach (@tacs);
</pre>
<br /><br />Refer to the classdocs for detailed descriptions of the various
T::A rendezvous methods, and the supporting TAC methods.</li>
</ul>
<h2 id="Best_Practices">Best Practices</h2>
<h3 id="Allocate_threads_and_TQDs_early">Allocate threads and TQDs early</h3>
<p>Due to Perl's heavyweight thread model (i.e., cloning
the entire parent thread context), threads that are spawned
after many modules have been loaded, or lots of objects
have been created, may consume significant unneeded resources.
By creating threads as early as possible, and deferring module
loading (i.e., not <code>use</code>'ing many/any modules, but rather
<code>require</code>'ing when needed), the apartment threads will be created
within the minimum required context.</p>
<h3 id="Use_T_A_set_single_threaded_for_debu">Use T::A::set_single_threaded() for debugging</h3>
<p>Debugging threaded applications
can be very challenging (not only Perl, but any language).
Perl's current debugger provides little or
no support for differentiating between the execution context
of different threads. Therefore, using the single threaded
implementation for preliminary test and debug is highly recommended.
While it may not surface issues related to concurrency, it will
usually be sufficient for finding and fixing most application logic
bugs.</p>
<h3 id="Wrap_Filehandles_With_Access_Discipl">Wrap Filehandles With Access Discipline Objects</h3>
<p>Given Perl's inability to marshall filehandles between
threads, wrapping handles with classes that provide the
access disciplines can be used to provide a marshal-able
solution, e.g., a Logger class that provides logging methods,
as well as file open, truncation, and close methods, and is
provided (as a TAC) to any other objects needing a logger.</p>
<h1 id="PREREQUISITES">PREREQUISITES <a href="#TOP" class="toplink"><img alt="^" src="../up.gif" /></a></h1>
<dl>
<dt>Perl 5.8.4 or higher</dt>
<dt><a href="http://search.cpan.org/perldoc?Thread%3A%3AQueue%3A%3ADuplex">Thread::Queue::Duplex</a> 0.92 or higher</dt>
<dt><a href="http://search.cpan.org/perldoc?Class%3A%3AISA">Class::ISA</a> 0.13 or later</dt>
<dt><a href="http://search.cpan.org/perldoc?Class%3A%3AInspector">Class::Inspector</a> 1.08 or later</dt>
<dt><a href="http://search.cpan.org/perldoc?Storable">Storable</a> 2.13 or later</dt>
</dl>
<h1 id="CHANGE_HISTORY">CHANGE HISTORY <a href="#TOP" class="toplink"><img alt="^" src="../up.gif" /></a></h1>
<h3 id="Release_0_50">Release 0.50</h3>
<ul>
<li>Renamed Thread::Apartment::IOServer to Thread::Apartment::EventServer
(TAIO to TAES) to more accurately reflect its purpose.</li>
<li>Renamed Thread::Apartment::setSingleThreaded to Thread::Apartment::set_single_threaded,
to conform to other naming. Also exported it.</li>
<li>Changed object hierarchy map from lexical in run() to a Thread::Apartment
class variables, with exported class methods to manipulate it.</li>
<li>Added CLONE methods to Thread::Apartment and Thread::Apartment::Server
to clear out class variables on thread clone</li>
<li>Added closure support</li>
<li>Added Thread::Apartment::MuxServer</li>
<li>Added Thread::Apartment::Container</li>
<li>Added support for async method return closures</li>
<li>Switched to Academic Free License</li>
<li>Added psichedocs</li>
<li>Added re-entrancy support via ta_reentrant_ prefix, AptReentrant,
and the set_/get_reentrant class methods</li>
</ul>
<h3 id="Release_0_10">Release 0.10</h3>
<ul>
<li>Initial release.</li>
</ul>
<h1 id="TO_DO">TO DO <a href="#TOP" class="toplink"><img alt="^" src="../up.gif" /></a></h1>
<h3 id="Filehandle_marshalling_support">Filehandle marshalling support</h3>
<p>Some means of transparently passing filehandles (as either
GLOBs, or subclasses of <a href="http://search.cpan.org/perldoc?IO%3A%3AHandle">IO::Handle</a>) would be nice. However,
it appears <strong>lots</strong> of things in Perl need to be fixed for
that to be a realistic option.<i><sigh/></i></p>
<h3 id="Operator_overloading">Operator overloading</h3>
<p>Some proxied method of supporting <a href="http://search.cpan.org/perldoc?overload">operator overloading</a> is needed
<i>(Though I personally dislike operator overloading)</i>. An early design
would add</p>
<pre> use overload nomethod => \&operAutoLoad;
</pre><p>to TACs, so that operators applied to a TAC could get redirected to
the associated TAS. However, a means of operator overload introspection
is also required so the TAS can report its operator overloads to the
TAC.</p>
<h3 id="lvalue_methods">lvalue methods</h3>
<p>Might be useful, but difficult to implement without some means
to detect the actual assignment event. Can be supported by TAC's
<strong>if</strong> the target variable is threads::shared, but then requires
some locking support as well.</p>
<h3 id="Provide_multiprocess_distributed_imp">Provide multiprocess/distributed implementation</h3>
<p>The infrastructure contained within Thread::Apartment should be readily
extendable to a multiprocess version, possibly using some lightweight IPC
mechanism in place of TQD's, and Storable to marshal/unmarshal
objects and method calls. Likewise, a fully distributed implementation should
be feasible using sockets in place of TQD's.</p>
<h3 id="Implement_AptSimplex_AptUrgent_metho">Implement AptSimplex, AptUrgent method attributes</h3>
<p>Rather than requiring a TAS subclass to provide get_simplex_methods()
and get_urgent_methods(), method <a href="http://search.cpan.org/perldoc?attributes">attributes</a> could be provided;
however, the status of attribute support in Perl 5 is a bit nebulous at
this time.</p>
<h3 id="Support_CLONE_SKIP">Support CLONE_SKIP()</h3>
<p>CLONE_SKIP has been added in Perl 5.8.8 to help avoid unneeded object
cloning (and thus improve performance and reduce memory footprint).
It would probably be useful to support this for the proxied objects.</p>
<h3 id="Implement_as_C_XS_or_Inline_C">Implement as C/XS or Inline::C</h3>
<p>Given the "CORE-ish" nature of T::A's behavior, a better performing
and more lightweight solution using C/XS would be desirable. But I suspect
there be dragons there...</p>
<h3 id="Implement_T_A_wrappers_for_commonly_">Implement T::A wrappers for commonly useful modules</h3>
<p>E.g., <a href="http://search.cpan.org/perldoc?HTTP%3A%3ADaemon">HTTP::Daemon</a>, <a href="http://search.cpan.org/perldoc?HTTP%3A%3ADaemon%3A%3ASSL">HTTP::Daemon::SSL</a>, <a href="http://search.cpan.org/perldoc?Class%3A%3ADBI">Class::DBI</a>, etc.
<i>DBI and Perl/Tk are already covered...</i></p>
<h3 id="Support_for_a_href_http_search_cpan_">Support for <a href="http://search.cpan.org/perldoc?Thread%3A%3AQueue%3A%3AMultiplex">Thread::Queue::Multiplex</a></h3>
<p>I have vague notions of how a publish/subscribe architecture
might exploit T::A, but need a reference application to get
a better idea how to implement.</p>
<h3 id="Better_Support_for_DESTROY">Better Support for DESTROY</h3>
<p>At present, reference counting and proxied object destruction are
not fully implemented. In addition, DESTROY events in the
TAC occur frequently, and appear to be duplicates or accidental,
e.g., in some instances, simply dereferencing a TAC from a hash
causes a DESTROY, even though the TAC has not bee removed from the
hash. Hence, it's difficult to determine when the proxied object should
be advised of a DESTROY event. At present, applications should assume
that apartment threaded objects will be retained for the life
of the application's execution.</p>
<h3 id="Add_a_Thread_Apartment_Rendezvous_cl">Add a Thread::Apartment::Rendezvous class</h3>
<p>The current implementation doesn't readily support initiation of
concurrent method requests, and waiting for them all to complete.
While asynchronous methods is a partial solution, it doesn't provide
a coordinated wait mechanism.</p>
<p>By adding a Thread::Apartment::Rendezvous
object, the initiating application could wait for completion
of all the started methods, and then proceed with processing.
An initial design would use an alternate method signature for async methods;
instead of passing a closure to be called when the method completed,
a T::A::Rendezvous <i>aka</i> <strong>TAR</strong> object would be provided. When the
method call was initiated, the TAC would pass itself and the generated
method request ID to the Rendezvous object.</p>
<p>Once the application had inititated all the methods, it would
invoke the TAR's <code>rendezvous()</code> method to wait for completion of
all the methods. Upon completion, the application could retrieve
results from individual TAC's using the request identifiers returned by
the previous async method call.</p>
<p>Example:</p>
<pre> my $rdvu = Thread::Apartment::Rendezvous->new();
...
my @pending = ();
push @pending, $tac1->ta_async_methodA($rdvu, @args);
push @pending, $tac2->ta_async_methodB($rdvu, @args);
push @pending, $tac3->ta_async_methodC($rdvu, @args);
$rdvu->rendezvous();
my $result1 = $tac1->ta_get_results(shift @pending);
my $result2 = $tac2->ta_get_results(shift @pending);
my $result3 = $tac3->ta_get_results(shift @pending);
</pre><p>However, some challenges remain:</p>
<ul>
<li>handling of returned results</li>
<li>coordinating simplex and duplex methods</li>
<li>coordinating re-entrant calls on the same TAC</li>
</ul>
<h1 id="SEE_ALSO">SEE ALSO <a href="#TOP" class="toplink"><img alt="^" src="../up.gif" /></a></h1>
<p><a href="http://search.cpan.org/perldoc?Thread%3A%3AQueue%3A%3ADuplex">Thread::Queue::Duplex</a>, <a href="http://search.cpan.org/perldoc?Thread%3A%3AQueue%3A%3AQueueable">Thread::Queue::Queueable</a>,
<a href="http://search.cpan.org/perldoc?DBIx%3A%3AThreaded">DBIx::Threaded</a>, <a href="http://search.cpan.org/perldoc?Tk%3A%3AThreaded">Tk::Threaded</a>, <a href="http://search.cpan.org/perldoc?Thread%3A%3AResource%3A%3ARWLock">Thread::Resource::RWLock</a>,
<a href="http://search.cpan.org/perldoc?threads%3A%3Ashared">threads::shared</a>, <a href="http://search.cpan.org/perldoc?perlthrtut">perlthrtut</a>, <a href="http://search.cpan.org/perldoc?Class%3A%3AISA">Class::ISA</a>, <a href="http://search.cpan.org/perldoc?Class%3A%3AInspector">Class::Inspector</a></p>
<p><a href="http://search.cpan.org/perldoc?Pots">Pots</a> and <a href="http://search.cpan.org/perldoc?Thread%3A%3AIsolate">Thread::Isolate</a> provide somewhat similar functionality,
but aren't quite as transparent as Thread::Apartment. They also do not
appear to support passing closures between threaded objects.</p>
<h1 id="AUTHOR_amp_COPYRIGHT">AUTHOR & COPYRIGHT <a href="#TOP" class="toplink"><img alt="^" src="../up.gif" /></a></h1>
<p>Copyright(C) 2005, 2006, Dean Arnold, 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>