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.00.
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.
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.