Module Lock_file.Nfs

module Nfs: sig .. end

An implementation neutral NFS lock file scheme that relies on the atomicity of link over NFS (see NFS Illustrated, atomicity for more information). Rather than relying on a working traditional advisory lock system over NFS we create a hard link between the file given to the create call and a new file <filename>.nfs_lock. This link call is atomic (in that it succeeds or fails) across all systems that have the same filesystem mounted. The link file must be cleaned up on program exit (normally accomplished by an at_exit handler, but see caveats below).

There are a few caveats compared to local file locks:

• These calls require the locker to have write access to the directory containing the file being locked.

• Unlike a normal flock call the lock may not be removed when the calling program exits (in particular if it is killed with SIGKILL).

val create : ?message:string -> string -> bool

lock ?message path tries to create and lock the file at path by creating a hard link to path.nfs_lock. The contents of path will be replaced with message, which will be the caller's hostname:pid by default.

Efforts will be made to release this lock when the calling program exits. But there is no guarantee that this will occur under some types of program crash. If the program crashes without removing the lock file an attempt will be made to clean up on restart by checking the hostname and pid stored in the lockfile.

val create_exn : ?message:string -> string -> unit

create_exn ?message path like create, but throws an exception when it fails to obtain the lock

val blocking_create : ?message:string -> string -> unit

blocking_create ?message path like create, but sleeps for 1 second between lock attempts and does not return until it succeeds

val critical_section : ?message:string -> string -> f:(unit -> 'a) -> 'a

critical_section ?message path ~f wrap function f (including exceptions escaping it) by first locking (using Lock_file.Nfs.create_exn) and then unlocking the given lock file.

val get_hostname_and_pid : string -> (string * Pid.t) option

get_hostname_and_pid path reads the lock file at path and returns the hostname and path in the file if it can be parsed.