VERSION
This documentation describes version 0.13.SYNOPSIS
use Thread::Tie; # use as early as possible for maximum memory savings
# use default thread + tieing + create thread when needed
tie $scalar, 'Thread::Tie';
tie @array, 'Thread::Tie';
tie %hash, 'Thread::Tie';
tie *HANDLE, 'Thread::Tie';
# use alternate implementation
tie $scalar, 'Thread::Tie',
{ module => 'Own::Tie::Implementation', # used automatically
use => 'Use::This::Module::Also', # optional, also as []
eval => 'arbitrary Perl code', # optional
};
# initialize right away
tie $scalar, 'Thread::Tie', {}, 10;
tie @array, 'Thread::Tie', {}, qw(a b c);
tie %hash, 'Thread::Tie', {}, (a => 'A', b => 'B', c => 'C');
tie *HANDLE, 'Thread::Tie', {},'>:layer','filename';
# create an alternate thread and use that
my $tiethread = Thread::Tie::Thread->new;
tie $scalar, 'Thread::Tie', {thread => $tiethread};
# object methods
my $tied = tie stuff,'Thread::Tie',parameters;
my $tied = tied( stuff );
my $semaphore = $tied->semaphore; # scalar for lock()ing tied variable
my $module = $tied->module; # module tied to in thread
my $tiethread = $tied->thread; # thread to which variable is tied
my $tid = $tiethread->tid; # thread id of tied thread
my $thread = $tiethread->thread; # actual "threads" thread
untie( stuff ); # calls DESTROY in thread, cleans up thoroughly
Thread::Tie->shutdown; # shut down default handling thread
$tiethread->shutdown; # shut down specific thread
DESCRIPTION
*** A note of CAUTION ***
This module only functions on Perl versions 5.8.0 and later.
And then only when threads are enabled with -Dusethreads. It
is of no use with any version of Perl before 5.8.0 or without
threads enabled.
*************************
The standard shared variable scheme used by Perl, is based on tie-ing the variable to some very special dark magic. This dark magic ensures that shared variables, which are copied just as any other variable when a thread is started, update values in all of the threads where they exist as soon as the value of a shared variable is changed.
Needless to say, this could use some improvement.
The Thread::Tie module is a proof-of-concept implementation of another approach to shared variables. Instead of having shared variables exist in all the threads from which they are accessible, shared variable exist as ``normal'', unshared variables in a separate thread. Only a tied object exists in each thread from which the shared variable is accessible.
Through the use of a client-server model, any thread can fetch and/or update variables living in that thread. This client-server functionality is hidden under the hood of tie(). So you could say that one dark magic (the current shared variables implementation) is replaced by another dark magic.
I see the following advantages to this approach:
- memory usage
- This implementation circumvents the memory leak that currently (threads::shared version 0.90) plagues any shared array or shared hash access.
- tieing shared variables
- Because the current implementation uses tie-ing, you can not tie a shared variable. The same applies for this implementation you might say. However, it is possible to specify a non-standard tie implementation for use within the thread. So with this implementation you can "tie()" a shared variable. So you could tie a shared hash to a DBM file a la dbmopen() with this module.
Of course there are disadvantages to this approach:
- pure perl implementation
- This module is currently a pure perl implementation. This is ok for a proof of concept, but may need re-implementation in pure XS or in Inline::C for production use.
- tradeoff between cpu and memory
- This implementation currently uses (much) more cpu than the standard shared variables implementation. Whether this would still be true when re-implemented in XS or Inline::C, remains to be seen.
tie()
You cannot activate this module with a named class method. Instead, you should tie() a scalar, array, hash or glob (handle). The appropriate class method will then be selected for you by Perl.Whether you tie a scalar, array, hash or glob, the first parameter to tie(), the second and third parameter (if specified) to tie() are always the same. And the tie() always returns the same thing: the blessed Thread::Tie object to which the variable is tied. You may or may not need that in your application. If you need to do lock()ing on the tied variable, then you need the object to be able to call the semaphore method.
class to tie with
You should always tie() to the class Thread::Tie. So the second parameter should always read 'Thread::Tie'. This parameter is not optional.reference to parameter hash
The third parameter is optional. If specified, it should be a reference to a hash with key/value pairs. The following fields may be specified in the hash.- module
-
module => 'Your::Tie::Implementation',
The optional ``module'' field specifies the module to which the variable should be tied inside the thread. If there is no ``module'' field specified, a standard tie implementation, associated with the type of the variable, will be assumed.
Please note that you should probably not use() the module yourself. The specified module will be use()d automatically inside the thread (only), avoiding bloat in all the other threads.
- use
-
use => 'Additional::Module', use => [qw(Additional::Module::1 Additional::Module::2)],
The optional ``use'' field specifies one or more modules that should also be loaded inside the thread before the variable is tied. These can e.g. be prerequisites for the module specified in the ``module'' field.
A single module can be specified by its name. If you need more than one module to be use()d, you can specify these in an array reference.
- eval
-
eval => 'any Perl code that you like;',
The optional ``eval'' field specifies additional Perl code that should be executed inside the thread before the variable is tied. This can e.g. be used to set up prerequisites.
Please note that the code to be executed currently needs to be specified as a string that is valid in an eval().
- thread
-
thread => Thread::Tie::Thread->new, thread => $thread,
The optional ``thread'' field specifies the instantiated Thread::Tie::Thread object that should be used to tie the variable in. This is only needed if you want to use more than one thread to tie variables in, which could e.g. be needed if there is a conflict between different tie implementations.
You can create a new thread for tie()ing with the ``new'' class method of the Thread::Tie::Thread module.
All the other input parameters are passed through to the tie() implementation of your choice. If you are using the default tie() implementation for the type of variable that you have specified, then the input parameters have the following meaning:
- scalar
-
tie my $scalar,'Thread::Tie',{},10;Initialize the tied scalar to 10.
- array
-
tie my @array,'Thread::Tie',{},qw(a b c);Initialize the tied array with the elements 'a', 'b' and 'c'.
- hash
-
tie my %hash,'Thread::Tie',{},(a => 'A', b => 'B', c => 'C');Initialize the tied hash with the keys 'a', 'b' and 'c' with values that are the uppercase version of the key.
- glob
-
tie *HANDLE,'Thread::Tie',{},">$file"; # 2 parameter open() tie *HANDLE,'Thread::Tie',{},'>',$file; # 3 parameter open()Initialize the tied glob by calling open() with the indicated parameters.
CLASS METHODS
There is only one named class method.shutdown
Thread::Tie->shutdown;
The ``shutdown'' class method shuts down the thread that is used for variables that have been tie()d without specifying an explicit thread with the ``thread'' field. It in fact calls the ``shutdown'' method of the Thread::Tie::Thread module on the instantiated object of the default thread.
Any variables that were tie()d, will not function anymore. Any variables that are tie()d after the thread was shut down, will automatically create a new default thread.
OBJECT METHODS
The following object methods are available for the instantiated Thread::Tie object, as returned by the tie() function.semaphore
my $semaphore = $tied->semaphore;
my $semaphore = (tie my $variable,'Thread::Tie)->semaphore;
my $semaphore = tied( $variable )->semaphore;
{lock( $semaphore ); do stuff with tied variable privately}
The ``semaphore'' object method returns a reference to a shared scalar that is associated with the tied variable. It can be used for lock()ing access to the tied variable. Scalar values can be assigned to the shared scalar without any problem: it is not used internally for anything other than to allow the developer to lock() access to the tied variable.
module
my $module = $tied->module; my $module = (tie my $variable,'Thread::Tie)->module; my $module = tied( $variable )->module;
The ``module'' object method returns the name of the module to which the variable is tied inside the thread. It is the same as what was (implicitely) specified with the ``module'' field when the variable was tied.
thread
my $tiethread = $tied->thread; my $tiethread = (tie my $variable,'Thread::Tie)->thread; my $tiethread = tied( $variable )->thread;
The ``thread'' object method returns the instantiated 'Thread::Tie::Thread' object to which the variable is tied. It is the same as what was (implicetely) specified with the ``thread'' field when the variable was tied.
REQUIRED MODULES
load (0.11) Thread::Serialize (0.07)