Provided by: libthread-tie-perl_0.13-1_all 
NAME
Thread::Tie - tie variables into a thread of their own
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)
CAVEATS
Because transport of data structures between threads is severely limited in the current
threads implementation (perl 5.8.0), data structures need to be serialized. This is
achieved by using the Thread::Serialize library. Please check that module for information
about the limitations (of any) of data structure transport between threads.
TODO
Examples should be added.
AUTHOR
Elizabeth Mattijsen, <liz@dijkmat.nl>.
Please report bugs to <perlbugs@dijkmat.nl>.
COPYRIGHT
Copyright (c) 2002-2003, 2010 Elizabeth Mattijsen <liz@dijkmat.nl>. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.
SEE ALSO
threads, Thread::Serialize.