Module Eio_fs_unix.Lease

Leases: BSD flock locks, which belong to an open file description rather than to the process that took them.

type t

The type for leases this process holds.

val fd : t -> Eio_unix.Fd.t

fd lease is the descriptor whose open file description owns the lease. A supervisor can inherit it before the callback returns. Closing the parent's descriptor does not release the lease while an inherited descriptor remains open. The descriptor must be closed, or the lease unlocked, to release it.

val unlock : t -> unit

unlock lease lets go of lease by the kernel's flock LOCK_UN on its open file description, so every descriptor sharing that description, one a supervisor inherited included, holds nothing from then on. The descriptors stay open. An exclusive callback still returns to let go of its process-local admission and its gate; a shared acquisition gives that admission back immediately.

val take : sw:Eio.Switch.t -> ?gate:_ Eio.Path.t -> ?block:[ block | `Readers ] -> ?create:create -> ?contents:string -> ?on_wait:(unit -> unit) -> _ Eio.Path.t -> t

take ~sw path acquires the exclusive lease described by with_exclusive. Its descriptor, process-local admission and gate remain held until release or sw's release hooks run. Acquisition has the same defaults, cancellation and refusals as with_exclusive, and raises as it does.

val release : t -> unit

release lease closes this holder's descriptor and gives back its process-local admission, then lets its gate go. Repeated calls do nothing. An inherited copy of the descriptor keeps its kernel lease until its last copy closes; use unlock to release the shared open file description immediately.

val with_exclusive : ?gate:_ Eio.Path.t -> ?block:[ block | `Readers ] -> ?create:create -> ?contents:string -> ?on_wait:(unit -> unit) -> _ Eio.Path.t -> (t -> 'a) -> 'a

with_exclusive path fn opens or creates path, takes an exclusive BSD flock, and calls fn with the descriptor that owns it. The lease is released when the last copy of that descriptor closes. The callback's descriptor is closed when the callback returns unless another process inherited it.

create (defaults to `If_missing 0o600, owner-only) says what an absent lock file does. contents, when present, replaces the lock file's contents while the lease is held. block (defaults to `Yes) says what a hold another caller already has does.

gate, when given, is a lease on a file of its own that every exclusive take of path passes: the take holds it exclusively before it takes path, and for as long as this descriptor holds path, until release or the callback's return, so no take of path is made between another's look at its holders and its take, as `Readers needs. A held gate is waited for or refused as block says of path, and the refusal is that of path's holder when an exclusive one holds it, else that of the take under way, whose contents (or nothing) the gate's file holds. The file is created when absent, with create's permissions or 0o600; its directory must exist. A take that finds path absent with create `Never removes the gate it holds. A caller that removes path holding it removes gate first, holding it too: a take that waited on a removed gate takes the file its name holds then.

With block `Yes or `For seconds, a lease another process holds is waited for by polling: the lease is tried without waiting, on_wait () is called once if it is held (it does nothing by default), and it is tried again after a sleep that starts at 1 ms and doubles up to 50 ms, until it is granted or `For seconds reaches its bound. A waiter takes no place in the kernel's queue, so waiters are not served in the order they arrived, and a release is noticed up to 50 ms late. With `Yes, `Fibers or `For seconds, a lease a fiber of this process holds is waited for in this process, and on_wait () is called before that wait too. A cancelled wait answers at the cancel and, like a wait that reached its bound, leaves no thread, descriptor or kernel request behind.

With block `Readers, which needs gate, only path's shared holders are waited for, as `Yes waits: an exclusive holder, or another take through gate under way, refuses the take as `No does. A reader's look, a shared lease taken and let go at once, delays the take and never refuses it. gate is tried without waiting and held throughout the wait, so no exclusive take comes in between this take's look at the holders and its own; the wait is sound only if every exclusive take of path passes gate.

Only a path backed by a native Unix descriptor can hold a lease. The path must name its own regular file; a link, directory, FIFO, or name changed between resolution and open is refused with Eio.Fs.error.Permission_denied carrying Not_a_lock_file.

Unlike with_lock, this operation does not unlock when fn returns. Closing the callback's descriptor releases the lock only when it was the last open descriptor referring to the same open file description.

  • raises Eio.Io

    as flock fails otherwise.

  • raises Invalid_argument

    when the filesystem provides no Unix descriptor, or when block is `Readers and no gate is given.

val with_shared : ?block:block -> ?create:create -> ?on_wait:(unit -> unit) -> _ Eio.Path.t -> (t -> 'a) -> 'a

with_shared path fn acquires a shared BSD flock on an independent open file description. Readers may overlap, including fibers of this process. An exclusive lease or with_lock excludes these readers. The creation, wait, cancellation and path checks are those of with_exclusive; readers take no gate and do not replace the lock file's contents.

Returning closes the callback's descriptor without unlocking. An inherited descriptor keeps the hold until its last copy closes. unlock releases this reader's hold and its process-local admission immediately, without releasing independently acquired readers.

It raises as with_exclusive does.