package dlm

  1. Overview
  2. Docs

OCaml bindings for libdlm(3).

v0.3.0 - homepage.

All operations require DLM (Linux Distributed Lock Manager) to be running.

Consult the lockspaces, and locks documentation or read the example.

References.

Lockspaces

Lockspaces are identified by a cluster-wide name, they are intended as private namespaces for locks belonging to a single application.

type t

the type of a DLM lockspace

val join : ?mode:PosixTypes.mode_t -> string -> unit Lwt.t

join ?mode lockspace creates and joins the specified lockspace on the current node.

Requires CAP_SYSADMIN privileges, access to the created lockspace is controlled by mode.

val leave : ?force:bool -> string -> unit Lwt.t

leave ?force lockspace leaves the specified lockspace on the current node.

  • parameter force

    will leave the lockspace even if the current node has active locks

val with_lockspace : string -> f:(t -> 'a Lwt.t) -> 'a Lwt.t

with_lockspace lockspace ~f opens an existing lockspace, calls f t with the lockspace handle t, and closes the lockspace after f terminates. The lockspace is also automatically closed on process exit.

Locks

Locks are a named cluster-wide resource inside a specific lockspace.

Only a simplified interface is provided that acquires a lock, performs an operation and releases it. Locking can be nested, even with same lock name, but note that trying to acquire an exclusive lock twice will fail.

It is recommended to use the LKM_PRMODE mode for reading and LKM_EXMODE for writing.

type mode =
  1. | LKM_NLMODE
    (*

    null lock - just allocate the lock, used internally by with_lock

    *)
  2. | LKM_CRMODE
    (*

    concurrent read - read while others can read/write.

    *)
  3. | LKM_CWMODE
    (*

    concurrent write - read/write while others can read/write.

    *)
  4. | LKM_PRMODE
    (*

    protected read - read, while others can only read.

    *)
  5. | LKM_PWMODE
    (*

    protected write - read/write, while others can only read

    *)
  6. | LKM_EXMODE
    (*

    exclusive - exclusive read/write, others have no access

    *)

lock mode

val with_lock : t -> ?mode:mode -> ?try_:bool -> ?timeout:float -> string -> f:(unit -> 'a Lwt.t) -> 'a Lwt.t

with_lock lshandle ?mode ?try_ ?timeout lockname ~f acquires lockname in lockmode and calls f when the lock is acquired. Releases the lock after f terminates.

  • parameter timeout

    specifies how long to wait for the lock to be acquired

  • parameter try_

    fail with EAGAIN if the lock cannot be granted immediately

Example

Need to be run as root, and with a working DLM. You can use dlm_tool status to check for a working DLM.

#use "topfind";;
#require "dlm";;
open Lwt.Infix;;

let lockspace = "myapp" in
Dlm.join lockspace >>= fun () ->
Dlm.with_lockspace lockspace (fun ls ->
    Dlm.with_lock ls "mylock1" ~f:(fun () ->
        (* acquired exclusive lock *)
        Lwt.return_unit
      ) >>= fun () ->
    Dlm.with_lock ~mode:Dlm.LKM_PRMODE ls "mylock1" ~f:(fun () ->
        (* acquired shared read lock *)
        Lwt.return_unit
      )
  ) >>= fun () ->
Dlm.leave lockspace