Provided by: libthread-tie-perl_0.15-2_all bug

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.