SUMMARY: CONSTR | METHOD | DETAIL: CONSTR | METHOD |
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.
Unless otherwise noted, $self
is the object instance variable.
Exported Symbols | |
---|---|
start | async method/closure request method |
rendezvous | method to wait for completion of async method/closure calls |
rendezvous_any | method to wait for completion of async method/closure calls |
rendezvous_until | method to wait for completion of async method/closure calls |
rendezvous_any_until | method to wait for completion of async method/closure calls |
Constructor Summary |
---|
new(AptClass => value, AptMaxPending => value, AptQueue => value, AptTimeout => value, AptParams => value, AptReentrant => value, AptAutoload => value, AptClosureCalls => value)
Factory method to create an instance of a class in an apartment thread |
Method Summary |
---|
CLONE()
ithreads CLONE() method to cleanup context when a new thread is spawned |
add_mapped_object($objid, $tac, $result, $isa, $methods)
(class method) Add an object to the object map |
add_object_reference($objid)
Increment the reference count for an object |
alloc_mapped_object()
(class method) Allocate a unique object ID |
create_pool(AptMaxPending => value, AptPoolSize => value)
(class method) Create a thread pool for apartment threaded objects |
destroy_object($objecid)
(class method) Destroy a mapped object |
destroy_pool()
(class method) Stop and remove all threads |
evict_objects()
(class method) Evict the current resident objects from the apartment thread |
free_thread()
(class method) Return a thread to the pool |
get_autoload()
(class method) Get current autoload setting |
get_closure($sig, $id)
(class method) Return the closure for a specified closure ID |
get_closure_behavior()
(class method) Get current closure call behaviors |
get_factory()
(class method) Factory constructor |
get_object_by_id($objid)
(class method) Return the object for a specified object ID |
get_object_methods($objid)
(class method) Return the hash map of method names to simplex/urgent flags for a specified object ID |
get_pending_request($tac)
(class method) Return the pending request ID for the input TAC |
get_reentrancy()
(class method) Get current re-entrancy setting |
get_tac_for_object($object)
(class method) Return the TAC for a mapped object |
install(AptClass => value, AptMaxPending => value, AptQueue => value, AptTimeout => value, AptParams => value, AptReentrant => value, AptAutoload => value, AptClosureCalls => value)
(class method) Install an object into the current thread |
map_async_request_id($key, $tac, $id)
(class method) Map a TAC to a async method/closure request ID |
register_closure($closure, $flags)
(class method) Registers a closure with the apartment thread before it is passed to another thread as either a parameter, or as a return value |
remove_thread()
(class method) Remove a thread from the pool |
rendezvous(@tac_list)
(class method) Wait for completion of pending method/closure requests on all of the specified TACs/closures |
rendezvous_any(@tac_list)
(class method) Wait for completion of pending method/closure requests on any of the specified TACs |
rendezvous_any_until($timeout, @tac_list)
(class method) Wait upto to $timeout seconds for completion of pending method/closure requests on any of the specified TACs |
rendezvous_until($timeout, @tac_list)
(class method) Wait upto to $timeout seconds for completion of pending method/closure requests on all of the specified TACs |
run()
(class method) Thread governor for installed objects |
run_wait($pendingq, $call_id, $timeout)
(class method) Intermediate thread governor for re-entrant method calls |
set_autoload($autoload)
(class method) Set autoload flag |
set_closure_behavior($behavior)
(class method) Set closure call behaviors |
set_reentrancy($reentrancy)
(class method) Set re-entrancy flag |
set_single_threaded()
(class method) Class method to force single threading |
start($tac_or_closure)
(class method) Starts an asynchronous method or closure call |
stop()
Stop and remove a thread |
Constructor Details |
---|
new(AptClass => value, AptMaxPending => value, AptQueue => value, AptTimeout => value, AptParams => value, AptReentrant => value, AptAutoload => value, AptClosureCalls => value)
The caller may supply a TQD ( and hence, the apartment thread) to be used as the communications channel between the apartment thread and client proxy instances. If not provided, either a thread and TQD are allocated from the existing pool (see create_pool()), or, if no pooled threads are available, a new apartment thread and TQD are created, in which to install the created object. By supplying a TQD, the application can create a pool of threads and TQDs as early as possible with the least context neccesary, and then allocate them to apartment threads as needed. However, the create_pool() method may be simpler for most applications.
Some default behaviors of the object(s) created/installed in the apartment thread may be directed using the AptReentrant, AptAutoload, or AptClosureCalls parameters (see below).
AptClass
=> class to be instantiated into an apartment thread
AptMaxPending
=> (optional) passed throught to any TQD created for the thread
AptQueue
=> (optional) Thread::Queue::Duplex
to be used to communicate to the proxied object(s)
AptTimeout
=> (optional) timeout (in seconds) for responses to any non-simplex
proxied method call.
AptParams
=> (optional) arrayref or hashref of parameters required for the proxied
class's constructor (if the object requires something other than
a hash for constructor parameters)
AptReentrant
=> (optional) boolean indicating whether the objects in the apartment
thread should permit re-entrancy (i.e., handle inbound method calls)
while waiting for the results of outbound calls to other T::A objects;
default is undef (false).
AptAutoload
=> (optional) boolean indicating whether the objects in the apartment
thread should permit any method call, rather than be restricted
to introspected, public methods. Default is undef (false).
AptClosureCalls
=> (optional) scalar string, or arrayref of strings, indicating whether
proxied closures called from objects in the apartment
should be treated as 'Simplex', 'Urgent', or both.
Default is undef (duplex, non-urgent). Valid (case-insensitive) values
are 'Simplex', 'Urgent', or an arrayref containing either or both of
those values.
Method Details |
---|
CLONE()
add_mapped_object($objid, $tac, $result, $isa, $methods)
$objid
- object ID
$tac
- the TAC (or possibly TACo) for the object
$result
- the object to map
$isa
- the class hierarchy of the object
$methods
- the method name map for the object
add_object_reference($objid)
$objid
- object ID
alloc_mapped_object()
create_pool(AptMaxPending => value, AptPoolSize => value)
require
'ing any modules, the threads will
have minimal context before the apartment thread objects
are installed into them.
AptMaxPending
=> used to set MaxPending on created TQD's.
AptPoolSize
=> the number of threads to create in the pool
destroy_object($objecid)
$objecid
- object ID
destroy_pool()
evict_objects()
free_thread()
get_autoload()
get_closure($sig, $id)
$sig
- closure signature (used to reject stale closures when an appartment thread is recycled)
$id
- closure ID
get_closure_behavior()
get_factory()
get_object_by_id($objid)
$objid
- object ID
get_object_methods($objid)
$objid
- object ID
get_pending_request($tac)
$tac
- TAC for which the pending request ID is to be returned
get_reentrancy()
get_tac_for_object($object)
$object
- the object (not the object ID!)
install(AptClass => value, AptMaxPending => value, AptQueue => value, AptTimeout => value, AptParams => value, AptReentrant => value, AptAutoload => value, AptClosureCalls => value)
Whereas new() creates a new instance of
a class and installs it in another thread, which immediately begins
monitoring the TQD channel for proxied method calls,
install()
creates a new instance of a class and installs it in the
current thread, returning a TACo,
which references both the actual created object, and its TAC, so the installed object
can be invoked within the current thread, yet still be distributed to other apartment
threaded objects.
When an application needs to pass an install()
ed object to other threads,
it has 2 options:
AptClass
=> class to be instantiated into an apartment thread
AptMaxPending
=> (optional) passed throught to any TQD created for the thread
AptQueue
=> (optional) Thread::Queue::Duplex
to be used to communicate to the proxied object(s)
AptTimeout
=> (optional) timeout (in seconds) for responses to any non-simplex
proxied method call.
AptParams
=> (optional) arrayref or hashref of parameters required for the proxied
class's constructor
AptReentrant
=> (optional) boolean indicating whether the objects in the apartment
thread should permit re-entrancy (i.e., handle inbound method calls)
while waiting for the results of outbound calls to other T::A objects;
default is undef (false).
AptAutoload
=> (optional) boolean indicating whether the objects in the apartment
thread should permit any method call, rather than be restricted
to introspected, public methods. Default is undef (false).
AptClosureCalls
=> (optional) scalar string, or arrayref of strings, indicating whether
proxied closures called from objects in the apartment thread
should be treated as 'Simplex', 'Urgent', or both.
Default is undef (duplex, non-urgent). Valid (case-insensitive) values
are 'Simplex', 'Urgent', or an arrayref containing either or both of
those values.
map_async_request_id($key, $tac, $id)
$key
- TAC or closure being mapped
$tac
- TAC to map to async request id
$id
- request id
register_closure($closure, $flags)
When another thread receives the TACl it will unmarshall it as a local closure that invokes a special method on the originating thread's TAC, which in turn will cause the originating thread to invoke the locally registered closure.
$closure
- closure to be registered
$flags
- bitmask of flags indicating simplex and/or urgent behavior
(see Thread::Apartment::Common
for bitmask values)
remove_thread()
rendezvous(@tac_list)
wait_all()
class method.
Note that the application is responsible for calling get_pending_results() on the appropriate TACs to get any method/closure return values.
For closures, the input parameter is the closure
@tac_list
- (optional) list of TACs or closures to wait for;
default is all pending TACs
rendezvous_any(@tac_list)
wait_any()
class method.
Note that the application is responsible for calling get_pending_results() on the appropriate TACs to get any method/closure return values.
For closures, the input TAC parameter is the TAC returned by start().
@tac_list
- (optional) list of TACs to wait for;
default is all pending TACs
rendezvous_any_until($timeout, @tac_list)
wait_all_until()
class method.
Note that the application is responsible for calling get_pending_results() on the appropriate TACs to get any method/closure return values.
For closures, the input TAC parameter is the TAC returned by start().
$timeout
- timeout in seconds to wait for completion
@tac_list
- (optional) list of TACs to wait for;
default is all pending TACs
rendezvous_until($timeout, @tac_list)
wait_all_until()
class method.
Note that the application is responsible for calling get_pending_results() on the appropriate TACs to get any method/closure return values.
For closures, the input TAC parameter is the TAC returned by start().
$timeout
- timeout in seconds to wait for completion
@tac_list
- (optional) list of TACs to wait for;
default is all pending TACs
run()
run_wait($pendingq, $call_id, $timeout)
Relies on the threads::shared nature of the thread pool map to recover the TQD for the thread in which the re-entrant call is made, and the non-threads::shared nature of the proxied object map to recover the root object.
$pendingq
- TQD of the proxied object with a pending call
$call_id
- request ID of the pending call
$timeout
- (optional) max. number of seconds to wait for an event
set_autoload($autoload)
$autoload
- the boolean value for the flag
set_closure_behavior($behavior)
$behavior
- the bitmask of TA_SIMPLEX and/or TA_URGENT values
set_reentrancy($reentrancy)
$reentrancy
- the boolean value for the flag
set_single_threaded()
start($tac_or_closure)
For async method calls, the parameter is the TAC object; for proxied
closure calls, the closure is specified. The returned value is the provided
TAC or closure, in order to support the following syntax
my $tac = Thread::Apartment::start($tac)->someMethod(@params); my $tac = Thread::Apartment::start($closure)->(@params);
$tac_or_closure
- TAC or closure to be invoked asynchronously
stop()