Fact.Lock (Fact v0.2.0)

View Source

Provides a cross-VM exclusive lock for Fact database instances.

This modules uses a UNIX Domain Socket to coordinate access to a Fact instance, ensuring that only one BEAM VM can perform certain operations at a time. The lock defines three modes.

  • :run - normal instance operation
  • :restore - doing an overwrite restore of a backup
  • :create - initialization of a new instance

Features

  • Cross-VM safe: Only one process across all BEAM VMs can hold the lock at a time.
  • Crash-safe: The lock is automatically released if the owning VM exits.
  • Stale cleanup: Detects and removes stale socket files left by crashed processes.
  • Metadata: Store JSON metadata including the OS PID, BEAM PID, BEAM node, lock mode, and timestamp.

Summary

Types

metadata()
metadata_record()

The deserialized representation of Fact.Lock.metadata/0, with string keys instead of atoms.

mode()
t()

Functions

acquire(database_id, mode)

Acquire a lock for the instance in the specified mode.

release(database_id, lock)

Release an acquired lock.

status(context)

Types

metadata()

@type metadata() :: %{
  mode: mode(),
  os_pid: pid(),
  vm_pid: pid(),
  node: node(),
  locked_at: binary()
}

metadata_record()

@type metadata_record() :: map()

The deserialized representation of Fact.Lock.metadata/0, with string keys instead of atoms.

mode()

@type mode() :: :run | :restore | :create

t()

@type t() :: %Fact.Lock{mode: mode(), socket: port(), socket_path: Path.t()}

Functions

acquire(database_id, mode)

@spec acquire(Fact.database_id(), mode()) ::
  {:ok, t()} | {:error, {:locked, metadata()}} | {:error, term()}

Acquire a lock for the instance in the specified mode.

release(database_id, lock)

@spec release(Fact.database_id(), t()) :: :ok

Release an acquired lock.

Closes the socket, deletes the socket file, and deletes the metadata file.

status(context)