locknamespacenamespace lockOne run at a time (commons 0001-system FR-015): a lock file made only where none exists (O_EXCL, which every file system and operating system gives atomically, where flock has no node: form), holding who holds it (process id, command, since when). A waiting run polls until it is free, says once who it waits for, and takes over a lock whose holder's process no longer runs. A child of a holder can inherit the lock through an environment variable instead of waiting for its own parent. Taken from Stolos's src/archon/core/lock.ts, which locked through the runtime's own file lock.
import { acquireLock } from "./lock.ts";
const held = await acquireLock("/run/app.lock", { wait: true, command: "update", onWait: (h) => console.log(`waiting for ${h?.command}`) });
try {
// the work
} finally {
held?.release();
}locknamespacenamespace locklock.Holdertypeno test imports ittype Holder = { readonly pid: number; readonly command: string; readonly since: string; readonly token: string };Who holds a lock.
lock.LockOptionstypeno test imports ittype LockOptions = {
/** Wait until it is free (polling), or give up at once. */
readonly wait: boolean;
/** What … (931 characters)type LockOptions = {
/** Wait until it is free (polling), or give up at once. */
readonly wait: boolean;
/** What the holder runs, said to whoever waits. */
readonly command?: string;
/** Called once, with the holder where it can be read, when the lock is not free. */
readonly onWait?: (holder: Holder | undefined) => void;
/** How often a waiting run looks again (250 ms by default). */
readonly pollMs?: number;
/** The variable that says a parent already holds the lock (no variable by default); it is set while the lock is held. */
readonly inheritEnv?: string;
/** How long a waiting run waits before it gives up and returns nothing (no limit by default). */
readonly timeoutMs?: number;
/** How old a lock file that cannot be read must be before it counts as abandoned (2 s by default): a file just made by a run that has not finished writing it is not. */
readonly unreadableGraceMs?: number;
};How to take a lock.
lock.Heldtypeno test imports ittype Held = {
/** Who holds it: this process. */
readonly holder: Holder;
/** The lock given back (the file removed where it is still this holder's); safe to call twice. */
release(): void;
};A lock taken.
lock.processRunsfunctionno test imports itfunction processRuns(pid: number): booleanWhether a process runs: a signal of 0 checks without sending one. A process of another account counts as running.
lock.readHolderfunctionno test imports itfunction readHolder(path: string): Promise<Holder | undefined>Who holds the lock at path, where its file can be read; whether that process still runs is not checked here.
lock.describeHolderfunctionno test imports itfunction describeHolder(h: Holder, now?: number): stringA holder as a person reads it: update (pid 4242, for 3m 12s).
lock.acquireLockfunctionno test imports itfunction acquireLock(path: string, options: LockOptions): Promise<Held | undefined>The lock at path taken, or undefined where it is held by a running process and wait is false (or timeoutMs passed). A lock whose holder no longer runs, or whose file cannot be read, is taken over. Where inheritEnv is set in the environment, a parent holds it, and it is given at once (its release does nothing).
Holdertypeno test imports ittype Holder = { readonly pid: number; readonly command: string; readonly since: string; readonly token: string };Who holds a lock.
LockOptionstypeno test imports ittype LockOptions = {
/** Wait until it is free (polling), or give up at once. */
readonly wait: boolean;
/** What … (931 characters)type LockOptions = {
/** Wait until it is free (polling), or give up at once. */
readonly wait: boolean;
/** What the holder runs, said to whoever waits. */
readonly command?: string;
/** Called once, with the holder where it can be read, when the lock is not free. */
readonly onWait?: (holder: Holder | undefined) => void;
/** How often a waiting run looks again (250 ms by default). */
readonly pollMs?: number;
/** The variable that says a parent already holds the lock (no variable by default); it is set while the lock is held. */
readonly inheritEnv?: string;
/** How long a waiting run waits before it gives up and returns nothing (no limit by default). */
readonly timeoutMs?: number;
/** How old a lock file that cannot be read must be before it counts as abandoned (2 s by default): a file just made by a run that has not finished writing it is not. */
readonly unreadableGraceMs?: number;
};How to take a lock.
Heldtypeno test imports ittype Held = {
/** Who holds it: this process. */
readonly holder: Holder;
/** The lock given back (the file removed where it is still this holder's); safe to call twice. */
release(): void;
};A lock taken.
processRunsfunctionfunction processRuns(pid: number): booleanWhether a process runs: a signal of 0 checks without sending one. A process of another account counts as running.
readHolderfunctionfunction readHolder(path: string): Promise<Holder | undefined>Who holds the lock at path, where its file can be read; whether that process still runs is not checked here.
describeHolderfunctionfunction describeHolder(h: Holder, now?: number): stringA holder as a person reads it: update (pid 4242, for 3m 12s).
acquireLockfunctionfunction acquireLock(path: string, options: LockOptions): Promise<Held | undefined>The lock at path taken, or undefined where it is held by a running process and wait is false (or timeoutMs passed). A lock whose holder no longer runs, or whose file cannot be read, is taken over. Where inheritEnv is set in the environment, a parent holds it, and it is given at once (its release does nothing).