Thread-Serialize-1.01/000755 000765 000765 00000000000 12060410425 014231 5ustar00lizliz000000 000000 Thread-Serialize-1.01/CHANGELOG000644 000765 000765 00000006267 12060410063 015454 0ustar00lizliz000000 000000 1.01 7 December 2012 Upgraded to Devel::MaintBlead 0.08. This should fix the problem as reported in https://rt.cpan.org/Ticket/Display.html?id=81354 by Justin Traer. Also upgraded the maint version to 0.14. 1.00 11 June 2012 Now uses Devel::ThreadsForks for checking whether running on a thread enabled Perl. Now uses Devel::MaintBlead to keep a maint and a blead version going. Blead version now no longer requires the "load" module: I considered it to have been a premature optimization that just caused a lot of grief. Raised the "maint" version to 0.13 as to distinguish it from the older, now maint version. Upgraded test-suite for blead to use the latest in Test::More's threading capabilities. 0.12 1 April 2012 Some cleanup in distro. Some code cleanup as well, as well as some code esthetics. Verified it work with 5.14.2. 0.11 20 September 2010 Checking the tool chain with perl 5.13.5. 0.10 29 September 2004 Added support for $Thread::Serialize::no_external_perl to prevent problems when used in embedded Perls. Spotted by Philip Monsen. Added documentation and additional tests in the test-suite. 0.09 28 December 2003 Added automatic required modules update using Devel::Required. 0.08 18 September 2003 Upgraded dependency on load to 0.10, since that has some significant Windows fixes. 0.07 17 September 2003 Upgraded dependency on load to 0.09. 17 August 2003 Some documentation fixes: we're not using AutoLoader anymore. 0.06 11 August 2003 Fixed some nits in Makefile.PL. Updated copyright notice. Fixed dependency on order of hash keys in test-suite: this caused spurious testing errors in 5.8.1. 0.05 30 September 2002 Removed support for AutoLoader and replaced it by support for "load.pm". Added dependency on "load" to Makefile.PL. Removed "our" from $VERSION, should shave off some bytes in memory usage, as found from testing with Benchmark::Thread::Size. 0.04 22 September 2002 Fixed warnings when running under -w. Thanks to Chris Rosebrugh for the spot. 0.03 10 September 2002 Removed the NOT_ICED environment variable hack and its documentation. Replaced by having an external Perl process calculate the Storable (iced) signature at load time. This should be compatible with all versions of Storable on all possible OS's and hardware architectures. 0.02 30 August 2002 Now uses pre-frozen signature value unless told otherwise. This saves Storable::freeze to have to be available in all threads. Can be circumvented by specifying NOT_ICED environment variable. Added OPTIMIZATIONS and CAVEATS sections to the pod. Added support for AutoLoader. Together with all of the other Thread:: modules, this should start saving a lot of memory. Removed reference tricks: we should find other ways of saving memory with threads. 0.01 13 August 2002 First version of Thread::Serialize. Thread-Serialize-1.01/lib/000755 000765 000765 00000000000 12060410425 014777 5ustar00lizliz000000 000000 Thread-Serialize-1.01/lib_maint/000755 000765 000765 00000000000 12060410425 016167 5ustar00lizliz000000 000000 Thread-Serialize-1.01/maintblead000644 000765 000765 00000013012 12060407077 016262 0ustar00lizliz000000 000000 #------------------------------------------------------------------------------- # This file was auto-generated by Devel::MaintBlead 0.08 on # Fri Dec 7 16:41:51 2012. # can also be called from Devel::MaintBlead, we need the main:: package package main; # mark that we've run this (for testing mostly) $Devel::MaintBlead::SIZE= 5642; # huh? if ( !$LIB_TREE or !$REQUIRED ) { print STDERR <<'HUH'; Please make sure the global variables $LIB_TREE and $REQUIRED are set before using the Devel::MaintBlead module in your Makefile.PL. HUH exit 1; } # private initializations my @lib_tree= split "/", $LIB_TREE; $lib_tree[$_]= "$lib_tree[ $_ - 1 ]/$lib_tree[$_]" foreach 1 .. $#lib_tree; my @postfix= qw( blead maint ); my %maint= map { $postfix[$_] => $_ } 0 .. $#postfix; my $auto_maint= ( $] < $REQUIRED ) || 0; #------------------------------------------------------------------------------- # set up file moving primitive use File::Copy (); sub mv { if ( -e $_[1] ) { print STDERR <<"HUH"; Cowardly refusing to overwrite $_[1] from $_[0] This should not happen. Please advise the author of Devel::MaintBlead on how you managed to do this. Thank you! HUH exit 1; } return File::Copy::mv(@_); } #mv #------------------------------------------------------------------------------- # set up file moving logic # # IN: 1 "from" interpolation # 2 "to" interpolation # 3 lib_tree setting (default: $LIB_TREE) sub mv_all { my ( $from, $to, $lib_tree )= @_; # move generic files if ( !$lib_tree ) { mv "MANIFEST$from", "MANIFEST$to" or die "Could not move file MANIFEST$from -> $to: $!\n"; foreach ( map { m#/([^/\.]+\.t)$from$# } glob( "t$from/*$from" ) ) { mv "t$from/$_$from", "t$to/$_$to" or die "Could not move file t$from/$_$from -> $to: $!\n"; } # use the base lib_tree $lib_tree= $LIB_TREE; } # just make sure it exists else { mkdir "lib$to/$lib_tree"; } # move lib files here foreach ( map { m#/([^/\.]+\.pm)$from$# } glob( "lib$from/$lib_tree/*$from" ) ) { mv "lib$from/$lib_tree/$_$from", "lib$to/$lib_tree/$_$to" or die "Could not move file $lib$from/$lib_tree/$_$from -> $to: $!\n"; } # remove now possibly empty subdirectories rmdir "lib$from/$lib_tree" if $from; # move them there for all subdirs mv_all( $from, $to, "$lib_tree/$_" ) foreach map { m#/([^/]+)$# } grep { -d } glob "lib$from/$lib_tree/*"; } #mv_all #------------------------------------------------------------------------------- # unlink_all # # IN: 1 initial directory to remove files from sub unlink_all { my ($dir)= @_; # remove all files from this dir (don't care whether worked) unlink glob "$dir/*"; # recursively unlink all files in all directories unlink_all($_) foreach grep { -d } glob "$dir/*"; } #unlink_all #------------------------------------------------------------------------------- # first time running Makefile.PL if ( !-e 'pm_to_blib' ) { # set default setting $MAINT= !glob( "lib_$postfix[1]/$LIB_TREE/*" ) || 0; open( OUT, ">default" ); print OUT $postfix[$MAINT]; close OUT; } # extract override if there is one my $type; @ARGV= grep { defined $maint{$_} ? ( $type= $_, $MAINT= $maint{$_}, 0 ) : 1 } @ARGV; # we have an override if ($type) { print STDERR "Forcing to use the '$type' version of the code\n"; open( OUT, ">default" ); print OUT $postfix[$MAINT]; close OUT; } # get default setting if necessary else { open( IN, 'default' ); $MAINT= $maint{ }; close IN; } # sorry, we can't help you if ( $auto_maint and !$MAINT ) { # can't do blead, autoselect active, so go to maint if ( $ENV{AUTO_SELECT_MAINT_OR_BLEAD} ) { $MAINT=1; } # alas, can't do blead else { $REQUIRED= sprintf '%1.6f', $REQUIRED; print STDERR <<"SORRY"; This distribution requires at least Perl $REQUIRED to be installed. Since this is an older distribution, with a history spanning almost a decade, it is also available inside this distribution as a previous incarnation, which is actively maintained as well. You can install that version of this distribution by running this $0 with the additional "maint" parameter, like so: $^X $0 maint @ARGV Or you can provide an automatic selection behavior, which would automatically select and install the right version of this distribution for the version of Perl provided, by setting the AUTO_SELECT_MAINT_OR_BLEAD environment variable to a true value. On Unix-like systems like so: AUTO_SELECT_MAINT_OR_BLEAD=1 $^X $0 @ARGV Thank you for your attention. SORRY my $line= (caller)[2]; eval <<"BYEBYE" or print STDERR $@; #line $line $0 require $REQUIRED; BYEBYE exit 1; } } # create shortcuts my $this= $postfix[$MAINT]; my $that= $postfix[ !$MAINT ]; # make sure empty directories exist, 'make dist' doesn't include them foreach my $postfix (@postfix) { mkdir "lib_$postfix"; mkdir "lib_$postfix/$_" foreach @lib_tree; mkdir "t_$postfix"; } # need to move files into place if ( my @files= glob( "lib_$this/$LIB_TREE/*" ) ) { print STDERR "Moving $this files into position\n"; # move current files away mv_all( '', "_$that" ); # put files into place mv_all( "_$this", '' ); # make sure we will copy to blib unlink_all("blib/lib/$LIB_TREE/*"); } # right files already there else { print STDERR "Files for $this already in position\n"; } Thread-Serialize-1.01/Makefile.PL000644 000765 000765 00000001204 11765413073 016215 0ustar00lizliz000000 000000 require 5.008; BEGIN { eval "use Devel::ThreadsForks; 1" or do 'threadsforks' } #BEGIN $LIB_TREE= 'Thread'; $REQUIRED= '5.014'; eval "use Devel::MaintBlead; 1" or do 'maintblead'; use ExtUtils::MakeMaker; eval "use Devel::Required maint_blead => $REQUIRED"; my @prereq= qw( Storable 0 ); push @prereq, $MAINT ? qw( load 0.10 ) : qw( Test::More 0.88 ); WriteMakefile ( NAME => "Thread::Serialize", AUTHOR => 'Elizabeth Mattijsen (liz@dijkmat.nl)', ABSTRACT => 'serialize data-structures between threads', VERSION_FROM => 'lib/Thread/Serialize.pm', LICENSE => 'perl', PREREQ_PM => { @prereq }, ); Thread-Serialize-1.01/MANIFEST000644 000765 000765 00000000726 12060410425 015367 0ustar00lizliz000000 000000 MANIFEST MANIFEST_maint CHANGELOG README Makefile.PL lib/Thread/Serialize.pm lib_maint/Thread/Serialize.pm_maint t/001basic.t t_maint/Serialize.t_maint META.yml Module meta-data (added by MakeMaker) threadsforks threads/forks test (added by Devel::ThreadsForks) maintblead maint/blead test (added by Devel::MaintBlead) META.json Module JSON meta-data (added by MakeMaker) Thread-Serialize-1.01/MANIFEST_maint000644 000765 000765 00000000602 11765407512 016566 0ustar00lizliz000000 000000 MANIFEST MANIFEST_blead CHANGELOG README Makefile.PL lib/Thread/Serialize.pm lib_blead/Thread/Serialize.pm_blead t/Serialize.t t_blead/001basic.t_blead META.yml Module meta-data (added by MakeMaker) threadsforks threads/forks test (added by Devel::ThreadsForks) maintblead maint/blead test (added by Devel::MaintBlead) Thread-Serialize-1.01/META.json000644 000765 000765 00000001644 12060410425 015657 0ustar00lizliz000000 000000 { "abstract" : "serialize data-structures between threads", "author" : [ "Elizabeth Mattijsen (liz@dijkmat.nl)" ], "dynamic_config" : 1, "generated_by" : "ExtUtils::MakeMaker version 6.6302, CPAN::Meta::Converter version 2.120630", "license" : [ "perl_5" ], "meta-spec" : { "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec", "version" : "2" }, "name" : "Thread-Serialize", "no_index" : { "directory" : [ "t", "inc" ] }, "prereqs" : { "build" : { "requires" : { "ExtUtils::MakeMaker" : "0" } }, "configure" : { "requires" : { "ExtUtils::MakeMaker" : "0" } }, "runtime" : { "requires" : { "Storable" : "0", "Test::More" : "0.88" } } }, "release_status" : "stable", "version" : "1.01" } Thread-Serialize-1.01/META.yml000644 000765 000765 00000001020 12060410425 015473 0ustar00lizliz000000 000000 --- abstract: 'serialize data-structures between threads' author: - 'Elizabeth Mattijsen (liz@dijkmat.nl)' build_requires: ExtUtils::MakeMaker: 0 configure_requires: ExtUtils::MakeMaker: 0 dynamic_config: 1 generated_by: 'ExtUtils::MakeMaker version 6.6302, CPAN::Meta::Converter version 2.120630' license: perl meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html version: 1.4 name: Thread-Serialize no_index: directory: - t - inc requires: Storable: 0 Test::More: 0.88 version: 1.01 Thread-Serialize-1.01/README000644 000765 000765 00000003207 12060410412 015107 0ustar00lizliz000000 000000 README for Thread::Serialize Library for data-structure serialization between threads. *** 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. ************************* Copyright (c) 2002, 2003, 2004, 2010, 2012 Elizabeth Mattijsen . All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Version: 1.01 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. Thread-Serialize-1.01/t/000755 000765 000765 00000000000 12060410425 014474 5ustar00lizliz000000 000000 Thread-Serialize-1.01/t_maint/000755 000765 000765 00000000000 12060410425 015664 5ustar00lizliz000000 000000 Thread-Serialize-1.01/threadsforks000644 000765 000765 00000001631 11765403753 016675 0ustar00lizliz000000 000000 #------------------------------------------------------------------------------- # This file was auto-generated by Devel::ThreadsForks 0.06 on # Mon Jun 11 09:59:55 2012. # mark that we've run this (for testing mostly) $Devel::ThreadsForks::SIZE= 921; # get configuration information require Config; Config->import; # no ithreads and no forks if ( !$Config{useithreads} and !eval { require forks; 1 } ) { print STDERR <<"TEXT"; ************************************************************************ * This distribution requires a version of Perl that has threads enabled * or which has the forks.pm module installed. Unfortunately, this does * not appear to be the case for $^X. * * Please install a threaded version of Perl, or the "forks" module * before trying to install this distribution again. ************************************************************************ TEXT # byebye exit 1; } Thread-Serialize-1.01/t_maint/Serialize.t_maint000644 000765 000765 00000002454 10126502031 021171 0ustar00lizliz000000 000000 BEGIN { # Magic Perl CORE pragma if ($ENV{PERL_CORE}) { chdir 't' if -d 't'; @INC = '../lib'; } } use Test::More tests => 16; use Thread::Serialize; # can't fake bare import call yet with Test::More use_ok( 'Thread::Serialize' ); can_ok( 'Thread::Serialize',qw( freeze thaw ) ); ok( !defined( $Thread::Serialize::no_external_perl ), "Check flag being unset" ); test(); delete $INC{'Thread/Serialize.pm'}; $Thread::Serialize::no_external_perl = 1; require Thread::Serialize; is( $Thread::Serialize::no_external_perl,'Signature obtained locally', "Check flag being set and changed" ); test(); sub test { my $scalar = '1234'; my $frozen = freeze( $scalar ); is( thaw($frozen),$scalar, 'check contents' ); my @array = qw(a b c); $frozen = freeze( @array ); is( join('',thaw($frozen)),join('',@array), 'check contents' ); $frozen = freeze( \@array ); is( join('',@{thaw($frozen)}),join('',@array), 'check contents' ); $frozen = freeze(); is( join('',thaw($frozen)),'', 'check contents' ); $frozen = freeze( undef ); ok( !defined( thaw($frozen) ), 'check contents' ); my %hash = (a => 'A', b => 'B', c => 'C'); $frozen = freeze( \%hash ); is( join('',sort %{thaw($frozen)}),join('',sort %hash),'check contents' ); } #test Thread-Serialize-1.01/t/001basic.t000644 000765 000765 00000003730 11765413452 016204 0ustar00lizliz000000 000000 BEGIN { # Magic Perl CORE pragma if ($ENV{PERL_CORE}) { chdir 't' if -d 't'; @INC = '../lib'; } } use strict; use warnings; my %Loaded; BEGIN { $Loaded{threads}= eval "use threads; 1"; $Loaded{forks}= eval "use forks; 1" if !$Loaded{threads}; } use Thread::Serialize; # can't fake bare import call yet with Test::More use Test::More; diag "threads loaded" if $Loaded{threads}; diag "forks loaded" if $Loaded{forks}; ok( $Loaded{threads} || $Loaded{forks}, "thread-like module loaded" ); my $class= 'Thread::Serialize'; can_ok( $class, qw( freeze thaw ) ); ok( !defined( $Thread::Serialize::no_external_perl ), "Check flag being unset" ); test(); delete $INC{'Thread/Serialize.pm'}; $Thread::Serialize::no_external_perl = 1; { local $SIG{__WARN__}= sub {}; # don't want to see warnings ever require Thread::Serialize; } is( $Thread::Serialize::no_external_perl,'Signature obtained locally', "Check flag being set and changed" ); test(); done_testing( 3 + 6 + 1 + 6 ); #------------------------------------------------------------------------------- # Good for 6 tests sub test { my $scalar= '1234'; my $frozen= freeze($scalar); is( thaw($frozen), $scalar, 'check contents' ); my @array= qw(a b c); $frozen= freeze(@array); is( join( '', thaw($frozen) ), join( '',@array ), 'check contents' ); $frozen= freeze( \@array ); is( join( '', @{ thaw($frozen) } ), join( '', @array ), 'check contents' ); $frozen= freeze(); is( join( '', thaw($frozen) ), '', 'check contents' ); $frozen= freeze(undef); ok( !defined( thaw($frozen) ), 'check contents' ); my %hash= ( a => 'A', b => 'B', c => 'C' ); $frozen= freeze( \%hash ); is( join( '', sort %{ thaw($frozen) } ), join( '', sort %hash ), 'check contents' ); } #test #------------------------------------------------------------------------------- Thread-Serialize-1.01/lib_maint/Thread/000755 000765 000765 00000000000 12060410425 017376 5ustar00lizliz000000 000000 Thread-Serialize-1.01/lib_maint/Thread/Serialize.pm_maint000644 000765 000765 00000013755 12060410350 023063 0ustar00lizliz000000 000000 package Thread::Serialize; $VERSION= '0.14'; # be as strict as possble use strict; # modules that we need use load; use Storable (); # use ourselves to determine signature our $iced; if ( $Thread::Serialize::no_external_perl ) { $iced= unpack( 'l',Storable::freeze( [] )); $Thread::Serialize::no_external_perl= 'Signature obtained locally'; } # use external perl to create signature else { open( my $handle, qq($^X -MStorable -e "print unpack('l',Storable::freeze( [] ))" | ) ) or die "Cannot determine Storable signature\n"; $iced= readline $handle; } # satisfy -require- 1; # The following subroutines are loaded on demand only __END__ #------------------------------------------------------------------------------- # freeze # # Freeze given parameters into a single scalar value # # IN: 1..N parameters to freeze # OUT: 1 frozen scalar sub freeze { # something to be frozen if (@_) { # any of the parameters is special, so really freeze foreach (@_) { return Storable::freeze( \@_ ) if !defined() or ref() or m#\0#; } # just concatenate with null bytes (WAY faster) return join( "\0", @_ ); } # no parameters, so just undef return; } #freeze #------------------------------------------------------------------------------- # IN: 1 frozen scalar to defrost # OUT: 1..N thawed data structure sub thaw { # nothing here or not interested return if !defined( $_[0] ) or !defined(wantarray); # return as list if (wantarray) { return ( unpack( 'l', $_[0] ) || 0 ) == $iced ? @{ Storable::thaw( $_[0] ) } : split "\0", $_[0]; } # scalar, really frozen, return first value elsif ( ( unpack( 'l',$_[0] ) || 0 ) == $iced ) { return Storable::thaw( $_[0] )->[0]; } # return first part of scalar return $_[0] =~ m#^([^\0]*)# ? $1 : $_[0]; } #thaw #------------------------------------------------------------------------------- # # Standard Perl Features # #------------------------------------------------------------------------------- sub import { shift; # determine namespace and subs my $namespace= caller().'::'; @_= qw( freeze thaw ) if !@_; # do our exports no strict 'refs'; *{$namespace.$_}= \&$_ foreach @_; return; } #import #------------------------------------------------------------------------------- __END__ =head1 NAME Thread::Serialize - serialize data-structures between threads =head1 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 ); =head1 VERSION This documentation describes version 0.14. =head1 DESCRIPTION *** A note of CAUTION *** This module only functions on threaded perl or an unthreaded perl with the "forks" module installed. Please also note that this documentation describes the "maint" version of this code. This version is essentially frozen. Please use a 5.14 or higher version of perl for the "blead" version of this code. ************************* 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 L, L or L can benefit from the same optimilizations that may take place here in the future. =head1 SUBROUTINES There are only two subroutines. =head2 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 L subroutine to obtain the original data-structure back. =head2 thaw my $scalar = thaw( $frozen ); my @array = thaw( $frozen ); The "thaw" subroutine returns the data-structure that was frozen with a call to L. 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 L are always matched by scalar context calls to L. =head1 REQUIRED MODULES load (0.10) Storable (any) =head1 OPTIMIZATIONS To reduce memory and CPU usage, this module uses L. 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 C<$Thread::Serialize::no_external_perl> variable to a true value at compile time B loading Thread::Serialize if this causes a problem. BEGIN { $Thread::Serialize::no_external_perl= 1 } use Thread::Serialize; =head1 KNOWN ISSUES =head2 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 C<$Thread::Serialize::no_external_perl> (see L). =head1 AUTHOR Elizabeth Mattijsen, . Please report bugs to . =head1 COPYRIGHT Copyright (c) 2002, 2003, 2004, 2010, 2012 Elizabeth Mattijsen . All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L, L, L, L. =cut Thread-Serialize-1.01/lib/Thread/000755 000765 000765 00000000000 12060410425 016206 5ustar00lizliz000000 000000 Thread-Serialize-1.01/lib/Thread/Serialize.pm000644 000765 000765 00000015743 12060410114 020500 0ustar00lizliz000000 000000 use 5.014; #package Thread::Serialize '1.01'; # not supported by PAUSE or MetaCPAN :-( package Thread::Serialize; # please remove if no longer needed our $VERSION= '1.01'; # please remove if no longer needed # be as verbose as possble use warnings;; # modules that we need use Storable (); # use ourselves to determine signature our $iced; if ( $Thread::Serialize::no_external_perl ) { $iced= unpack( 'l',Storable::freeze( [] )); $Thread::Serialize::no_external_perl= 'Signature obtained locally'; } # use external perl to create signature else { open( my $handle, qq( $^X -MStorable -e "print unpack( 'l', Storable::freeze( [] ) )" | ) ) or die "Cannot determine Storable signature\n"; $iced= readline $handle; } # satisfy -require- 1; #------------------------------------------------------------------------------- # freeze # # Freeze given parameters into a single scalar value # # IN: 1..N parameters to freeze # OUT: 1 frozen scalar sub freeze { # something to be frozen if (@_) { # any of the parameters is special, so really freeze foreach (@_) { return Storable::freeze( \@_ ) if !defined() or ref() or m#\0#; } # just concatenate with null bytes (WAY faster) return join( "\0", @_ ); } # no parameters, so just undef return; } #freeze #------------------------------------------------------------------------------- # IN: 1 frozen scalar to defrost # OUT: 1..N thawed data structure sub thaw { # nothing here or not interested return if !defined( $_[0] ) or !defined(wantarray); # return as list if (wantarray) { return ( unpack( 'l', $_[0] ) || 0 ) == $iced ? @{ Storable::thaw( $_[0] ) } : split "\0", $_[0]; } # scalar, really frozen, return first value elsif ( ( unpack( 'l',$_[0] ) || 0 ) == $iced ) { return Storable::thaw( $_[0] )->[0]; } # return first part of scalar return $_[0] =~ m#^([^\0]*)# ? $1 : $_[0]; } #thaw #------------------------------------------------------------------------------- # # Standard Perl Features # #------------------------------------------------------------------------------- sub import { shift; # determine namespace and subs my $namespace= caller().'::'; @_= qw( freeze thaw ) if !@_; # do our exports no strict 'refs'; *{$namespace.$_}= \&$_ foreach @_; return; } #import #------------------------------------------------------------------------------- __END__ =head1 NAME Thread::Serialize - serialize data-structures between threads =head1 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 ); =head1 VERSION This documentation describes version 1.01. =head1 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 L, L or L can benefit from the same optimilizations that may take place here in the future. =head1 SUBROUTINES There are only two subroutines. =head2 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 L subroutine to obtain the original data-structure back. =head2 thaw my $scalar = thaw( $frozen ); my @array = thaw( $frozen ); The "thaw" subroutine returns the data-structure that was frozen with a call to L. 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 L are always matched by scalar context calls to L. =head1 REQUIRED MODULES Storable (any) Test::More (0.88) =head1 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. =head1 OPTIMIZATIONS To reduce memory and CPU usage, this module uses L. 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 C<$Thread::Serialize::no_external_perl> variable to a true value at compile time B loading Thread::Serialize if this causes a problem. BEGIN { $Thread::Serialize::no_external_perl= 1 } use Thread::Serialize; =head1 KNOWN ISSUES =head2 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 C<$Thread::Serialize::no_external_perl> (see L). =head1 AUTHOR Elizabeth Mattijsen, . Please report bugs to . =head1 COPYRIGHT Copyright (c) 2002, 2003, 2004, 2010, 2012 Elizabeth Mattijsen . All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L, L, L, L. =cut