Persistent(3pm)

📦
version 1.00 · 2 versions
  • 1.00 · debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
  • 1.00 · ubuntu jammy
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

✨ Persistent(3pm) ✨

okay so this is the manual for Tie::Persistent, from the User Contributed Perl Documentation corner of the perl-verse 💖 it's called Persistent(3pm) btw, section 3pm, so you know exactly what you're getting into bestie 🎀

🌸 NAME 🌸

Tie::Persistent — persistent data structures via tie made easy 💅 no cap, that's literally it.

⭐ VERSION ⭐

1.00

🦋 SYNOPSIS 🦋

 use Tie::Persistent;

 tie %DB, 'Tie::Persistent', 'file', 'rw'; # read data from 'file'

 (tied %DB)->autosync(1);       # turn on write back on every modify

 # now create/add/modify datastruct
 $DB{key} = "value";
 (tied %DB)->sync();            # can be called manually

 untie %DB;                     # stores data back into 'file'

 # read stored data, no modification of file data
 tie %ReadOnly, 'Tie::Persistent', 'file';
 foreach (keys %ReadOnly) {
   print "$_ => $ReadOnly{$_}\n";
 }
 untie %ReadOnly;               # modifications not stored back

like... it's giving effortless ✨

💖 DESCRIPTION 💖

the Tie::Persistent package makes working with persistent data real easy by using the tie interface. iconic behaviour honestly 🫶

how it works: it stores the data inside a variable into a file (not unlike a database, lowkey). the primary advantage is speed, because the whole datastructure is kept in memory — which is also, yes, a limitation 😭 — and, of course, that you can use arbitrary data structures inside the variable (unlike DB_File). main character energy fr.

note that it is most useful if the data structure fits into memory. for larger data structures, the author recommends MLDBM. 💜

if you want to make an arbitrary object persistent, just store its ref in a scalar tied to 'Tie::Persistent'. slay.

beware 💀 not every data structure or object can be made persistent. for example, it may not contain GLOB or CODE refs, as these are not really dumpable (yet?).

also — it works only for variables. you cannot use it for file handles.

and then the author goes off on one, and honestly? we respect it:

[A persistent file handle? Hmmm... Hmmm! I've got an idea: I could start a server and send the file descriptor to it via ioctl(FD_SEND) or sendmsg. Later, I could retrieve it back, so it's persistent as long as the server process keeps running. But the whole file handle may contain more than just the file descriptor. There may be an output routine associated with it that I'd somehow have to dump. Now let's see, there was some way to get the bytecode converted back into perl code... <wanders off into the darkness mumbling> ... ]

🎀 PARAMETERS 🎀

 "tie" %Hash,   'Tie::Persistent', file, mode, other...;

 "tie" @Array,  'Tie::Persistent', file, mode, other...;

 "tie" $Scalar, 'Tie::Persistent', file, mode, other...;

🌈 file

the filename to store the data in. no naming convention is enforced, but the author personally uses the suffix 'pd' for "Perl Data" (or "Persistent Data"?). nobody's policing you. no file locking is done — see the section on locking below, bestie 👀

🌈 mode (optional)

same as mode for POSIX fopen() or IO::File::open. basically a combination of 'r', 'w', 'a' and '+'. semantics go like this:

 'r' .... read only. Modifications in the data are not stored back
          into the file. A non-existing file gives an error. This is
          the default if no mode is given.

 'rw' ... read/write. Modifications are stored back, if the file does
          not exist, it is created.

 'w' .... write only. The file is not read, the variable starts out empty.

 'a', '+' ... append. Same as 'w', but creates numbered backup files.

 'ra', 'r+' ... Same as 'rw', but creates numbered backup files.

when some kind of write access is specified, a backup file of the old dataset is always created. [You'll thank me for that, believe me.] the reason is simple: when you tie a variable read-write (the contents get restored from the file), and your program isn't fully debugged yet, it may die in the middle of some modifications, but the data will still be written back to the file, possibly leaving them inconsistent 😭 then you always have at least the previous version that you can restore from. it's giving safety net 💅

the default backup filenames follow the Emacs notation, i.e. a '~' is appended; for numbered backup files (specified as 'a' or '+'), an additional number and a '~' is appended.

so for a file 'data.pd', the normal backup file would be 'data.pd~' and the numbered backup files would be 'data.pd~1~', 'data.pd~2~' and so on. the latest backup file is the one with the highest number. the backup filename format can be overridden — see below. 👑

🌈 other (optional, experimental)

this can be a reference to another (possibly tied) variable, or a name of another tieable package.

if a ref is given, it is used internally to store the variable data instead of an anonymous variable ref. this allows one to make other tied datastructures persistent — e.g. you could first tie a hash to Tie::IxHash to make it order-preserving and then give it to Tie::Persistent to make it persistent. obsessed 😍

a plain name is used to create this tied variable internally. trailing arguments are passed to the other tieable package.

example:

 tie %h, 'Tie::Persistent', 'file', 'rw', 'Tie::IxHash';

or

 tie %ixh, 'Tie::IxHash';
 tie %ph,  'Tie::Persistent', 'file', 'w', \%ixh;
 # you can now use %ixh as an alias for %ph
NOTE: this is an experimental feature 🙈 it may or may not work with other Tie:: packages. the author has only tested it with 'Tie::IxHash'. please report success or failure!

🔒 LOCKING 🔒

the data file is not automatically locked. locking has to be done outside of the package. the author recommends using a module like 'Lockfile::Simple' for that. 🫶

there are typically two scenarios for locking: you either lock just the 'tie' and/or 'untie' calls, but not the data manipulation, or you lock the whole 'tie' – modify data – 'untie' sequence.

🧚 KEEPING DATA SYCHRONIZED 🧚

(yes, that's the section title, we're keeping it exactly as written 💀)

it often is useful to store snapshots of the tied data struct back to the file, e.g. to safeguard against program crashes. you have two possibilities to do that:

  • use sync() to do it manually, or
  • set autosync() to do it on every modification.

note that sync() and autosync() are methods of the tied object, so you have to call them like this:

 (tied %hash)->sync();

and

 (tied @array)->autosync(1);  # or '0' to turn off autosync

there is a global variable $Autosync (see there) that you can set to change the behaviour on a global level for all subsequent ties.

enabling autosync of course means a quite hefty performance penalty, so think carefully if and how you need it 😭 maybe there are natural synchronisation points in your application where a manual sync is good enough. alternatively use MLDBM (if your top-level struct is a hash).

Note: autosync only works if the top-level element of the data structure is modified. if you have more complex data structures and modify elements somewhere deep down, you have to synchronize manually.

so the author therefore recommends the following approach, especially if the topmost structure is a hash:

  • fetch the top-level element into a temporary variable
  • modify the datastructure
  • store back the top-level element, thus triggering a sync.

e.g.

 my $ref = $Hash{$key};      # fetch substructure
 $ref->{$subkey} = $newval;  # modify somewhere down under
 $Hash{$key} = $ref;         # store back

this programming style has the added advantage that you can switch over to other database packages (for example the MLDBM package, in case your data structures outgrow your memory) quite easily by just changing the 'tie' line! ✨ glow-up friendly ✨

🍓 CONFIGURATION VARIABLES 🍓

$Tie::Persistent::Readable controls which format to use to store the data inside the file. 'false' means to use 'Storable', which is faster (and the default); 'true' means to use 'Data::Dumper', which is slower but much more readable and thus meant for debugging. this only influences the way the datastructure is written — format detection on read is automatic. 🦋

$Tie::Persistent::Autosync gives the default for all tied vars, so modifying it affects all subsequent ties. it's set to 'false' by default.

$Tie::Persistent::BackupFile points to a sub that determines the backup filename format. it gets the filename as $_[0] and returns the backup filename. the default is

 sub { "$_[0]~"; }

which is the Emacs backup format. for NT, you might want to change this to

 sub { "$_[0].bak"; }

or something.

$Tie::Persistent::NumberedBackupFile points to a sub that determines the numbered backup filename format. it gets the filename and a number as $_[0] and $_[1] respectively and returns the backup filename. the default is

 sub { "$_[0]~$_[1]~"; }

which is the extended Emacs backup format.

🌈 NOTES 🌈

  • 'Tie::Persistent' uses 'Storable' and 'Data::Dumper' internally, so these must be installed (the CPAN module will do this for you automatically). actually, 'Storable' is optional but recommended for speed. ⚡
  • for testing, the author uses 'Tie::IxHash', but 'make test' still does some tests if it is not installed.
  • there are two mailing lists at SourceForge.net:

http://lists.sourceforge.net/mailman/listinfo/persistent-announce for announcements of new releases.

http://lists.sourceforge.net/mailman/listinfo/persistent-discuss for user feedback and feature discussions.

💀 BUGS 💀

numbered backupfile creation might have problems if the filename (not the backup number) contains the first six digits of the speed of light (in m/s). 🧚 iconic bug report honestly.

all other bugs, please tell me!

👑 AUTHORS 👑

original version by Roland Giersig <RGiersig@cpan.org>

Benjamin Liberman <beanjamman@yahoo.com> added autosyncing and fixed splice.

Copyright (c) 1999-2002 Roland Giersig. 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 ⭐

Storable, Data::Dumper, MLDBM.

and that's the whole page bestie 🫶 go forth and tie responsibly. this was perl v5.36.0, dated 2022-11-20, and we're closing out Persistent(3pm) — periodt 💅✨

📦 where this page comes from