Fugu
Fugu::StateFile(3p) Perl Library Manual Fugu::StateFile(3p)

Fugu::StateFile - a small JSON state file

    use Fugu::StateFile;
    my $store = Fugu::StateFile->new(
        path => '/var/db/myapp/state.json',
        mode => 0600,
    )->load;
    $store->set(installed => 1);
    my $installed = $store->get('installed');

Fugu::StateFile is the file where a daemon and its tools keep the handful of facts that must survive a restart: a counter, a flag, a timestamp. It is that file and nothing more. It holds no PID logic and starts no subprocess: Fugu::Pidfile owns the first, and the caller owns the second.

load() tolerates a missing file and a corrupt one. A state file that a crash truncated must not stop the program that would rewrite it. save() is atomic, through Fugu::File, so the file is never the corrupt one that the next load() has to tolerate.

new(%args) creates a store. The method does not touch the file. Call load().

These are the arguments:

"path"
The state file. This argument is necessary.
"mode"
The file mode. The default is 0600, because a state file often holds a secret and a wider mode is a decision, not a default.

load() reads the state. An absent file gives empty state with no error. A corrupt file gives empty state and records the reason in error(), so the caller can report it and carry on. The method returns the object either way.

save() writes the state, with the mode applied before the content.

get($key) returns one value, or "undef".

"set($key, $value)" stores one value and saves. A caller that changes several keys uses data() and save() instead of one call for each.

delete($key) removes one value and saves.

data() returns the state hash reference itself. A caller that changes several keys at once changes it and then calls save().

path() returns the state file.

error() returns the most recent failure.

load() returns the object. save(), set() and delete() return the object on success and "undef" on failure, with the reason in error().

get() returns a value or "undef". data() returns a hash reference.

This example changes two keys with one write:

    $store->data->{running}    = 1;
    $store->data->{started_at} = time;
    $store->save or warn $store->error . "\n";

new() dies when "path" is absent or empty. That is a programming error.

No other method dies. A failed read and a failed write both report through the return value and error().

Fugu::Config, Fugu::File, Fugu::Pidfile

Dick Olsson <hi@senzilla.io>

The store is not shared state. Two processes that hold the same file both keep their own copy in memory, and the last save() wins. A process that must not lose a concurrent change reloads before it writes, or takes a lock of its own.

Every value goes through JSON. A code reference, a file handle, or a blessed object does not encode, and the save() that meets one fails.

2026-10-16 OpenBSD