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

Hash::Persistent::Memory

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.