@rivus/agent-kit-collab/process-lock
acquireProcessLock, isProcessLockHeld, ProcessLock, ProcessLockPlatform — plain TS
Functions
acquireProcessLock()
function acquireProcessLock(
platform: ProcessLockPlatform,
path: string,
options?: ProcessLockOptions
): Promise<Result<ProcessLock, ProcessLockHeld>>;A single-instance lock on path, which must be in an existing local directory (not NFS). With platform.sqlite,
path is a SQLite database held with locking_mode=EXCLUSIVE: the kernel releases it when the process exits or
crashes, at once, and nothing is ever reclaimed. The holder's identity goes into <path>.holder for diagnostics
only, so a process that cannot read its own identity (platform.process.self throws: always on win32, which is not
supported, and on darwin in a sandbox that denies running ps or sysctl) still takes the lock: its holder is
undefined, and instead of writing <path>.holder it removes one that a dead holder left. Without SQLite, path
is a lock file that holds the identity itself; a lock file whose holder died is reclaimed on the next attempt, which
needs the holder on this host (see tryFileLock for the remaining gaps). The lock file cannot go without the
identity: the call rejects with the error reading it, and takes nothing.
With removeOnRelease the release also removes the lock file itself, so a caller that takes one lock per item does
not leave one file per item behind; see ProcessLockOptions for how the acquisition keeps the removal from breaking
mutual exclusion.
Acquisitions of one lock in this process take turns in memory (see takeTurn): while one holds the lock or is
attempting it, the next waits for it to release the lock or give up, then makes its own attempt, so none of them
blocks the thread in a SQLite busy wait on a holder in this process. Without wait, a call that finds the turn taken
resolves to ProcessLockHeld at once, without attempting, with the holder read from the lock's record.
Supports darwin and linux.
Parameters
platform
path
string
options?
ProcessLockOptions
Returns
Promise<Result<ProcessLock, ProcessLockHeld>>
isProcessLockHeld()
function isProcessLockHeld(
platform: ProcessLockPlatform,
path: string,
options?: IsProcessLockHeldOptions
): Promise<boolean>;Parameters
platform
path
string
options?
Returns
Promise<boolean>
Interfaces
IsProcessLockHeldOptions
Whether another process, or an acquisition in this one, holds the process lock on path, checked without taking
it: the check writes nothing (no <path>.holder, and a missing lock file stays missing and reads as free). The
answer may be stale by the time it arrives, so it can choose between handing work to the holder and starting one,
but it does not replace acquiring. The check never waits, so signal is consulted once, before it starts: an
aborted signal rejects with signal.reason without touching the lock file.
With platform.sqlite it makes one attempt at a shared lock on the database, with no busy timeout and no retries,
and never reads the process identity; checks running at once do not see each other as holders. The first attempt of
an acquireProcessLock running at the same moment still gets a free lock; the later retries of wait: true can
find it busy while a check reads it, and get it one backoff later. Without SQLite it reads the lock file and judges
its holder as acquireProcessLock does, which reads the process identity, and leaves a dead holder's file for the
next acquisition to reclaim.
Properties
signal?
readonly signal?: AbortSignal;ProcessLock
A held process lock. Releasing it is the caller's job; the lock also ends when the process exits.
Properties
holder
readonly holder: ProcessLockHolder | undefined;Who took the lock, as recorded for diagnostics. undefined only with sqlite, when this process could not read its
own identity (see acquireProcessLock).
mechanism
readonly mechanism: "sqlite" | "file";sqlite when the platform has SQLite; file is the weaker fallback (see acquireProcessLock).
path
readonly path: string;Methods
release()
release(): Promise<void>;Releases the lock; later calls do nothing.
Returns
Promise<void>
Type Aliases
ProcessLockPlatform
type ProcessLockPlatform = Pick<Platform, "fs" | "process" | "clock" | "sqlite">;The part of Platform a process lock uses. With sqlite the lock is an exclusive SQLite lock; without it, a lock
file. process supplies this process's identity, which a SQLite lock records for diagnostics and a lock file is
judged by.