NAME
Hash::Persistent - nested hashref serializable to the file
VERSION
version 1.02
SYNOPSIS
use Hash::Persistent;
$obj = Hash::Persistent->new("./obj.state"); # give a file to keep state
$obj->{string} = "hello world"; # and use just like a regular perl hash
$obj->commit; # save the data to the state file
$obj->{string} = "world hello";
undef $obj; # force destroying; data will not be saved
$obj = Hash::Persistent->new("./obj.state", { auto_commit => 1 });
$obj->{string} = "hello world";
undef $obj; # the last update is commited
$obj = Hash::Persistent->new("./obj.state", { read_only => 1 }); # do not flock
print $obj->{string};
$obj->{string} = "hello"; # ok, local modifications
$obj->commit; # dies, cannot commit a readonly persistent
$obj = Hash::Persistent->new("./obj.state", {}, {blocking => 0}); # pass some options to flock call
$obj = Hash::Persistent->new("./obj.state", {format => "storable"});
undef $obj; # recode state into storable format
foreach my $key (%$obj) {} # $obj is guaranteed not to contain any internal keys
DESCRIPTION
Hash::Persistent
serializes its data to the single file using Data::Dumper, Storable or JSON.
The object reads the state from given file when created, and writes the new state when destroyed. No multithreading - the file is locked with flock
while object exists.
METHODS
- new($options, $lock_options)
-
These constructor options are supported:
- auto_commit
-
If true, state will be commited when object is destroyed.
It is recommended not to turn this option on and call
commit()
explicitly every time, because perl ignores all exceptions thrown from destructors.Off by default.
- read_only
-
If set, object can't be commited, auto_commit can't be set, and object won't try to obtain a lock.
Off by default.
- write_only
-
Supressing the loading of data from an existing file. Useful for generating a new state and avoid failures if the previous one is currupted. It also can be used for minor performance improvements.
Off by default.
- lock
-
If true, take the global waiting lock for the whole lifetime of the object.
On by default.
- mode
-
If set, it will chmod the output file to the given value after each commit.
- format
-
Possible values: dumper, storable, json.
If not specified and file already exists, will be detected automatically. If not specified and file doesn't exist, json will be used as default.
json format is fast, readable and secure, but can't serialize objects.
dumper format is human-readable and can serialize objects, but insecure and slow.
storable format can serialize objects and fast, but unreadable by humans and insecure.
Additionally, any
Lock::File
options can be passed as a third parameter. - commit()
-
Write data on disk.
File will be written in atomic fashion, using tmpfile, so when disk is full, data will not be lost.
- remove()
-
Remove persistent file.
This method is lock-unsafe, which means that you shouldn't try to create persistent file again soon after this call.
SEE ALSO
AUTHORS
Vyacheslav Matyukhin <me@berekuk.ru>
Andrei Mishchenko <druxa@yandex-team.ru>
Artyom V. Kulikov <breqwas@yandex-team.ru>
COPYRIGHT AND LICENSE
This software is copyright (c) 2015 by Yandex LLC.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.