Thread...rialize(3pm)

📦
version 1.03 · 2 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

✨ NAME ✨

Thread::Serialize — serialize data-structures between threads 💖

(yes bestie, the manual name is literally Thread...rialize(3pm), it got squished by the terminal, but we're talking about Thread::Serialize here 🎀)

🌸 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.03. slay.

💜 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.
*

Okay so listen 👑 — the Thread::Serialize module is a library for centralizing the routines used to serialize data-structures between threads. And why do we care about the central location?? Because of this central location, other modules such as Thread::Conveyor, Thread::Pool or Thread::Tie can benefit from the same optimizations that may take place here in the future. it's giving "shared infrastructure, main character energy" 💅

🎀 SUBROUTINES 🎀

There are only two subroutines. two. iconic minimalism fr fr ✨

🧊 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. Then use the thaw subroutine to obtain the original data-structure back. no cap, that's the whole deal 🫶

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

bestie that last one is on YOU, not on the module 😭 keep your context matched.

🌈 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. automatic slay 💅

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. so like, lazy-loading but make it ✨efficient✨

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;
heads up bestie — that variable has to be set at compile time, before you load Thread::Serialize, or it won't do the thing 🙈

💀 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). we love a fixed bug 🫶

👑 AUTHOR 👑

Elizabeth Mattijsen, <liz@dijkmat.nl>.

Maintained by LNATION, <email@lnation.org>

Please report bugs to <email@lnation.org>.

Copyright (c) 2002, 2003, 2004, 2010, 2012 Elizabeth Mattijsen <liz@dijkmat.nl>. 2025 LNATION <email@lnation.org> 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.

and that's the whole page bestie, you ate it 💖 this was perl v5.40.1, dated 2025-04-25, from the Thread...rialize(3pm) page — go forth and serialize, periodt ✨🎀

📦 where this page comes from