Skip to content
Belikhun edited this page Sep 15, 2026 · 1 revision

🔒 Lock

A named lock only one process can hold at a time, across every host that shares the database.

use Blink\Lock;

Lock::of("reports:rebuild") -> run(function () {
	Reports::rebuild();
}, ttl: 600, wait: 30);

run() acquires, runs the callable, releases, and rethrows anything the callable threw. wait is how long to keep trying before giving up with LockAcquired; 0 tries once.

By hand:

$lock = Lock::of("imports:daily");

if (!$lock -> acquire(ttl: 300))
	return;

try {
	Importer::run();
	$lock -> refresh(300);   // a long job extends its own claim
} finally {
	$lock -> release();
}
Method Does
acquire($ttl, $throw) Take the lock now, or return false. Takes over an expired claim.
block($wait, $ttl, $throw) Retry for up to $wait seconds
release() Give it back, if this instance still holds it
refresh($ttl) Push the expiry out
held() Whether anyone holds it
holder() Who: host, pid, when, and where in the code

Time to live

Every lock expires. A holder that crashes leaves its claim behind, and the expiry is what lets the next process continue instead of waiting on one that is never coming back. It also means a holder that overruns its TTL no longer owns the lock; anything it does after that point has to be safe to happen twice, or it should refresh() along the way. The default TTL is Lock::DEFAULT_TTL.

Stores

Lock::of() uses CONFIG::$LOCK_STORE, database by default: a row in the locks table, which works across hosts. Lock::file() uses a file under DATA_ROOT, for the one lock that has to exist before the table does, Terra's own. Lock::database() names the database store explicitly.

php core/blink lock:list
php core/blink lock:release reports:rebuild --force

lock:list shows every held lock with its holder, which is where an orbit entry marked alone() shows up while it runs.

Clone this wiki locally