The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Thread-Serialize-0.14
River stage one • 2 direct dependents • 6 total dependents
++
/ Thread::Serialize

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

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

 load (0.10)
 Storable (any)

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.