NAME

App::FileSync::Lock - advisory lock files

SYNOPSIS

my $lock = App::FileSync::Lock::acquire(path => $path, nonblock => 1)
	or exit 2;	# another run holds it
# ... the lock is released when $lock goes out of scope

FUNCTIONS

acquire

Purpose: take an exclusive flock on a file.

Args: path (required), nonblock (return at once instead of waiting).

Returns: the filehandle holding the lock, or undef when nonblock is set and another process holds it. The lock lasts until the handle is closed or goes out of scope.

Side Effects: creates the file and its directory if needed.

Usage:

my $lock = App::FileSync::Lock::acquire(path => $lock_path, nonblock => 1);

EXAMPLE

if (my $lock = App::FileSync::Lock::acquire(path => '/tmp/demo.lock', nonblock => 1)) {
	print "got it\n";
}

API SPECIFICATION

INPUT

{
	path     => { type => 'string', min => 1 },
	nonblock => { type => 'boolean', optional => 1 },
}

OUTPUT

{ type => 'handle', optional => 1 }

MESSAGES

Key            Meaning                        Resolution
args.invalid   no path was given              pass path
io.append      the lock file cannot be made   check permissions

FORMAL SPECIFICATION

ΔLocks
path? : PATH ; nb? : 𝔹 ; h! : HANDLE ∪ {⊥}
path? ¬in; dom Locks ⇒ h! ≠ ⊥ ∧ Locks' = Locks ∪ {path? ↦ self}
path? ∈ dom Locks ∧ nb? ⇒ h! = ⊥ ∧ Locks' = Locks

LIMITATIONS

flock is advisory and, on NFS, may not lock across machines at all. Keep the server root and the client's ~/.filesync on local disks.

AUTHOR

Nigel Horne, <njh at nigelhorne.com>

LICENCE AND COPYRIGHT

Copyright 2026 Nigel Horne.

Usage is subject to the GPL2 licence terms. If you use it, please let me know.