Glossary

TQD - Thread::Queue::Duplex

The communications channel used between apartment threads.

TQQ - Thread::Queue::Queueable

Abstract class that specifies the curse() and redeem() methods used for marshalling objects across a TQD.

POPO - Plain Old Perl Object

An object that does not implement Thread::Apartment::Server

thread governor

The primary control loop of an apartment thread. Usually provided by the "Thread::Apartment"'s internal "_run()" 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 TAMS below).

T::A - Thread::Apartment object

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.

TAS - Thread::Apartment::Server

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.

TAC - Thread::Apartment::Client

A threads::shared object that provides the proxy for Thread::Apartment::Server objects, and can be shared/passed between threads.

TACo - Thread::Apartment::Container

A lightweight, non-shared proxy container object that resides in the same thread as its "install()"ed (not 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 "install()"'ed objects to be manipulated by the application within the installed thread before turning over control of the thread to the apartment threaded object.

TAES - Thread::Apartment::EventServer

Subclass of Thread::Apartment::Server to provide a poll() method that is called by the thread governor at regular intervals to detect and process class-specific events, e.g., polling I/O handles.

TAMS - Thread::Apartment::MuxServer

Subclass of Thread::Apartment::Server that inverts the control scheme for classes which must implement their own thread governor, e.g., Tk::Threaded.

TACl - Thread::Apartment::Closure

A simple class used to contain and marshal closures between apartment threads.

Application Notes and Restrictions

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.

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 Tk::Threaded), you'll need to create a class and create or install an instance of it in an apartment thread.

Passing filehandles

Filehandles (aka GLOBs) 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 IO::Handle::fdopen() or open(FH, "&$fileno")).

Despite best efforts, no consistent solution for marshalling and esp. unmarshalling filehandles - while preserving their access modes and PerlIO 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.

Therefore, applications are responsible for providing their own mechanisms for marshalling filehandles between threads.

Cannot Provide Proxied Access to Members of Tied Objects

Since TAC is itself a threads::shared object, and threads::shared objects cannot be tied, it is not possible to proxy the tied "STORE", "FETCH", etc. methods. Note that this does not 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.

It may be possible to create a non-threads::shared subclass of TAC to support the tied capability; refer to DBIx::Threaded for hints on how to support tied objects.

Proxied operator overloading not supported

Operator overloading is not currently supported. A future version of T::A may provide a means to proxy overloaded operators, ala proxied closures.

Proxied lvalue methods not supported

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.

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 (since the TAC is threads::shared, it members are available to the TAS thread). 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.

AUTOLOADing in Apartment Threaded Packages

In order to minimize proxy overhead, when an object is installed into an apartment thread, the object's @ISA hierarchy (as reported by Class::ISA::self_and_super_path), and the list of available public methods (as reported by Class::Inspector::methods()) are exported to the client proxy objects, so that "isa()" and "can()" 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.

However, classes which need to rely on AUTOLOADing can specify that in a number of ways:

• override TAS's "introspect()" method by including the AUTOLOAD method name in the returned list of declared methods
• override TAS's "introspect()" method and call T::A's "set_autoload" method to force AUTOLOAD support for all objects within the apartment.
• specify a true value for T::A::new/install() "AptAutoload" parameter (useful for creating apartment threaded POPO's which need AUTOLOADing)

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 "can()" method calls will be passed to the TAS if an undeclared method is referenced

Use "$self->isa()", not "ref $self"

Due to the exported @ISA described above, using the "ref" operator on the client stub objects will report a TAC or TACo object, rather than the proxied object. TAC overrides the "UNIVERSAL::isa()" method to test the exported @ISA hierarchy.

Subclassing Thread::Apartment::Server

TAS provides implementations of several abstract methods which may be overridden in subclasses. Refer to the Thread::Apartment::Server classdocs for method details.

I/O Bound Classes

Classes which detect/trap I/O (or other async) events should inherit from TAES and provide an implementation of its "poll()" method, in order to interleave the apartment thread's TQD "dequeue()" calls and the detection of internal events. E.g., a network socket monitor which calls "select()" to detect socket events would implement the "select()" call with some small timeout inside its "poll()" implementation. "Thread::Apartment::run()" detects the installation of a TAES object, and will use TQD's "dequeue_nb()" method, rather than "dequeue()", to check for incoming method calls, and, if none are available, will call the object's "poll()" method to permit the object to field any events.

Classes with Control Loops

Classes which encapsulate their own control loops (e.g., Perl/Tk) should inherit from TAMS and frequently call "Thread::Apartment::MuxServer::handle_method_requests()" 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 "run()" method when the internal T::A::_run() method is called.

Subclassing Thread::Apartment::Client

When a TAS based class is used, the class may override the "create_client()" 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 threads::shared scalar, array, or hash refs, in order to avoid the overhead of making a proxied method call.

Refer to the Thread::Apartment::Client classdocs for detailed descriptions of its methods.

Installing POPO's

In order to provide the greatest possible flexibility, T::A supports installing Plain Old Perl Objects aka POPOs. POPOs do not implement the TAS class, and thus can be nearly any existing class definition, with the following limitations:

• Constructor must be "new()"
• All methods must be declared, i.e., no AUTOLOAD support
• All methods are called as duplex, non-urgent
• Methods that return "undef" are assumed to be returning an error, with any error text in $@

Externally Created Threads Must Run "Thread::Apartment::run()"

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 "Thread::Apartment::run()" method, e.g.,

        #
        #       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;
        }

Errors Returned as "undef", with Error Text in $@

T::A assumes that any non-simplex method that returns "undef" has an error, and the error message is available in $@ (as for "eval{}" operations). An application specific adapter class may be required to adapt existing classes to this error reporting behavior.

Object-returning Methods

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 "curse()" and "redeem()" 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 (aka "Zone Threading"), and will

• add it to its object heirarchy map
• assign it a unique ID
• generate a TAC for it, using the current T::A's TQD
• return the TAC instance, rather than the object itself

Note that, in the event the object has previously been mapped in the hierarchy, the existing TAC instance for the object will be reused.

T::A (via TAS::marshalResults()) does not do a deep inspection of returned values to detect instances of non-TAC objects.

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.

Cyclic Object/Method Dependencies

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

• declaring A's method2() as simplex. However, this option is not viable if "method2()" returns a value, and deadlock may still result if object A starts another blocking proxied call after the call to "method2()".
• using an asynchronous method call with a completion closure (see "Asynchronous Method Calls"). 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().
• using re-entrancy on object A's thread while calling object B. Re-entrancy can be set in any of the following ways:

setting the AptReentrant constructor parameter

calling T::A::set_reentrancy(1)

using the "ta_reentrant_" method prefix for method1()

The re-entrancy approach causes the TAC for object B to use a special "Thread::Apartment::run_wait()" 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 "method2". The class-method version of Thread::Queue::Duplex::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.

Note that using the "ta_reentrant_" 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 Thread::Apartment::set_reentrancy(0) is called to disable re-entrancy.

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.

Unexpected TAC AUTOLOADs for Indirect Object References

If an object is indirectly referenced via a hash, e.g., "$objmap->{'MyObject'}->someMethod();", TAC's AUTOLOAD may get a DESTROY method reference, rather than the expected 'someMethod' value (the reasons for this are not yet clear...). As a result, it may be neccesary to dereference the object into a lexical variable to invoke the method, e.g.,

        my $temp = $objmap->{'MyObject'};
        $temp->someMethod();

Further investigation is needed to determine the reason for this behavior.

Passing/Invoking Closures Between T::A Objects

Managing closures in T::A relies on ithread's isolation of class variables between threads, i.e., assume SomeClass declares

        package SomeClass;

        our $variable;

Further assume that SomeClass is loaded into 2 different threads. Then modifying $SomeClass::variable in thread A does not effect the current value of $SomeClass::variable in thread B.

Hence, T::A declares the following non-threads::shared class variables:

%closure_map

A map of closure IDs 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.

$next_closure_id

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.

$closure_signature

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.

$closure_tac

A TAC used to proxy all closures generated within the thread.

When a new root object is installed into an apartment thread, the %closure_map and $next_closure_id variables are reset, and $closure_signature is set to the current timestamp.

2 methods for passing closures are supported: either directly as CODEREF's, or by creating Thread::Apartment::Closure aka 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.

The following methods are provided to support creating TACl's explicitly:

$self->new_tacl(CODEREF)

Generates a regular TACl object. CODEREF will be invoked in duplex, non-urgent mode.

$self->new_simplex_tacl(CODEREF)

Generates a simplex TACl object. CODEREF will be invoked in simplex, non-urgent mode.

$self->new_urgent_tacl(CODEREF)

Generates an urgent TACl object. CODEREF will be invoked in duplex, non-urgent mode.

$self->new_urgent_simplex_tacl(CODEREF)

Generates a simplex, urgent TACl object. CODEREF will be invoked in simplex, urgent mode.

E.g.,

        #
        #       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"; }));

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.

Default closure call behavior can be modified via either

• Setting the "T::A::new/install(AptClosureCalls)" parameter to 'Simplex', 'Urgent', or both, e.g.

          my $tac = Thread::Apartment->new(...
                  AptClosureCalls => [ 'Simplex', 'Urgent'],
                  ...);
      

  (useful for specifying behavior for POPO's).

• Overriding the default TAS "introspect" method to call "T::A::set_closure_behavior()" with a bitmask of the "TA_SIMPLEX" and/or "TA_URGENT" values.

The following acronyms are used in the following detailed discussion:

CRTAC - Closure Recipient TAC

TAC for the object to which the closure is being passed.

CRTAS - Closure Recipient TAS

TAS for the object to which the closure is being passed.

CGTAC - Closure Generator TAC

TAC for the object which generated the closure.

CGTAS - Closure Generator TAC

TAS for the object which generated the closure.

Processing of CODEREF Closures

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.

1.

The CRTAC calls Thread::Apartment::register_closure, passing the CODEREF.

2.

"register_closure" 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.

3.

The CRTAC then marshals the signature, ID, and CGTAC as a TACl object in the marshalled stream.

4.

When the CRTAS detects the TACl object in the request stream, it converts the object into a local closure call on the CGTAC:

        sub { $cgtac->ta_invoke_closure($signature, $id, @_); }
    

which the CRTAS can then apply in the proxied method call as a regular CODEREF.

5.

When the CRTAS eventually calls the closure, the invoke_closure() method is marshalled as usual by the CGTAC (possibly including the marshalling of proxied closures from the CRTAS), except that the simplex and urgent bits if $id are checked to determine if the closure requires any special queueing (as for a simplex or urgent method).

6.

The CGTAS recognizes the "ta_invoke_closure()" 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.

Processing of TACl Closures

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.

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.

The remainder of the closure processing is identical to the CODREF case.

Closures as Return Values

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.

Limitations

In its current implementation, the marshalling/unmarshalling process does not detect closures deep within structures passed between threads. In such cases, the Storable package used to marshal/unmarshal complex non-threads::shared structures between threads will throw an error.

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.

Asynchronous Method Calls

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:

• If a called method is prefixed with "ta_async_", 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.,

          #
          #       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 @_
                  #
          }
      

  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.

• Using Thread::Apartment's "start()" and "rendezvous()" methods to start a method or closure, and then later wait for it (and possibly other pending requests). E.g.,

          #
          #       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);
      

  Refer to the classdocs for detailed descriptions of the various T::A rendezvous methods, and the supporting TAC methods.

Best Practices

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 "use"'ing many/any modules, but rather "require"'ing when needed), the apartment threads will be created within the minimum required context.

Use T::A::set_single_threaded() for debugging

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.

Wrap Filehandles With Access Discipline Objects

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.