Provided by: libthread-tie-perl_0.15-2_all 
NAME
Thread::Tie - tie variables into a thread of their own
VERSION
This documentation describes version 0.15.
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 à 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 (implicitly) 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>.
maintained by LNATION, <thisusedtobeanemail@gmail.com>
Please report bugs to <thisusedtobeanemail@gmail.com>.
COPYRIGHT
Copyright (c) 2002-2003, 2010 Elizabeth Mattijsen <liz@dijkmat.nl>, 2019 LNATION
<thisusedtobeanemail@gmail.com>. 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.
perl v5.36.0 2022-10-14 Thread::Tie(3pm)