oracular (3) Thread::Serialize.3pm.gz

NAME

       Thread::Serialize - serialize data-structures between threads

SYNOPSIS

         use Thread::Serialize;    # export freeze() and thaw()

         use Thread::Serialize (); # must call fully qualified subs

         my $frozen = freeze( any data structure );
         any data structure = thaw( $frozen );

VERSION

       This documentation describes version 1.02.

DESCRIPTION

                         *** A note of CAUTION ***

        This module only functions if threading has been enabled when building
        Perl, or if the "forks" module has been installed on an unthreaded Perl.

                         *************************

       The Thread::Serialize module is a library for centralizing the routines used to serialize data-structures
       between threads.  Because of this central location, other modules such as Thread::Conveyor, Thread::Pool
       or Thread::Tie can benefit from the same optimilizations that may take place here in the future.

SUBROUTINES

       There are only two subroutines.

   freeze
        my $frozen = freeze( $scalar );

        my $frozen = freeze( @array );

       The "freeze" subroutine takes all the parameters passed to it, freezes them and returns a frozen
       representation of what was given.  The parameters can be scalar values or references to arrays or hashes.
       Use the thaw subroutine to obtain the original data-structure back.

   thaw
        my $scalar = thaw( $frozen );

        my @array = thaw( $frozen );

       The "thaw" subroutine returns the data-structure that was frozen with a call to freeze.  If called in a
       scalar context, only the first element of the data-structure that was passed, will be returned.
       Otherwise the entire data-structure will be returned.

       It is up to the developer to make sure that single argument calls to freeze are always matched by scalar
       context calls to thaw.

REQUIRED MODULES

        Storable (any)
        Test::More (0.88)

INSTALLATION

       This distribution contains two versions of the code: one maintenance version for versions of perl < 5.014
       (known as 'maint'), and the version currently in development (known as 'blead').  The standard build for
       your perl version is:

        perl Makefile.PL
        make
        make test
        make install

       This will try to test and install the "blead" version of the code.  If the Perl version does not support
       the "blead" version, then the running of the Makefile.PL will *fail*.  In such a case, one can force the
       installing of the "maint" version of the code by doing:

        perl Makefile.PL maint

       Alternately, if you want automatic selection behavior, you can set the AUTO_SELECT_MAINT_OR_BLEAD
       environment variable to a true value.  On Unix-like systems like so:

        AUTO_SELECT_MAINT_OR_BLEAD=1 perl Makefile.PL

       If your perl does not support the "blead" version of the code, then it will automatically install the
       "maint" version of the code.

       Please note that any additional parameters will simply be passed on to the underlying Makefile.PL
       processing.

OPTIMIZATIONS

       To reduce memory and CPU usage, this module uses load.  This causes subroutines only to be compiled in a
       thread when they are actually needed at the expense of more CPU when they need to be compiled.  Simple
       benchmarks however revealed that the overhead of the compiling single routines is not much more (and
       sometimes a lot less) than the overhead of cloning a Perl interpreter with a lot of subroutines pre-
       loaded.

       To reduce the number of modules and subroutines loaded, an external Perl interpreter is started to
       determine the Storable signature at compile time.  In some situations this may cause a problem: please
       set the $Thread::Serialize::no_external_perl variable to a true value at compile time before loading
       Thread::Serialize if this causes a problem.

        BEGIN { $Thread::Serialize::no_external_perl= 1 }
        use Thread::Serialize;

KNOWN ISSUES

   Embedded Perls
       Philip Monsen reported that in the case of an embedded Perl interpreter (e.g.  in a C program), the use
       of an external executor to determine the Storable signature, causes problems.  This has been fixed by
       introducing the global variable $Thread::Serialize::no_external_perl (see OPTIMIZATIONS).

AUTHOR

       Elizabeth Mattijsen, <liz@dijkmat.nl>.

       Please report bugs to <perlbugs@dijkmat.nl>.

COPYRIGHT

       Copyright (c) 2002, 2003, 2004, 2010, 2012 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

       load, Thread::Conveyor, Thread::Pool, Thread::Tie.