Multi-resource Web Locks need an application-level order
Web Locks coordinate same-origin tabs and workers, but mutual exclusion for one name does not prevent deadlock across several names. The failure occurs when one context holds settings and waits for accounts, while another holds accounts and waits for settings. Both locks remain held because each request callback is still waiting for the next callback to complete.
The implementation decision is to define one global order for every multi-resource operation. Normalize the requested names, sort them lexically, and reject duplicates before making any lock request. Every caller must use the same rule; otherwise two code paths can still create opposite acquisition orders. Sorting is not a scheduling hint for the browser. It is the application contract that removes the circular-wait edge.
Acquire the ordered names through nested LockManager.request() callbacks. Each callback returns the next acquisition, and the final callback runs the protected work only after all locks have been granted. This structure matters because a Web Lock is released when its callback returns, including when an async callback’s promise settles. Starting dependent work after an outer callback returns means the earlier lock is no longer owned.
The expected result is simple: two contexts that request the same resource set in different input orders still ask for locks in the same order. The work receives the acquired locks only after the complete chain is active. If a fail-fast request uses ifAvailable and a later lock is unavailable, the work does not run and the already-entered callbacks return, releasing earlier locks.
Shared mode is appropriate for compatible readers; exclusive mode remains appropriate for writers. ifAvailable means do not wait, while an abort signal means stop waiting when cancellation is requested. Neither option makes opposite-order acquisition safe.
There is an important testing limit. A deterministic recording fixture can verify sorting, callback ownership, duplicate rejection, and the fail-fast unwind path. It does not reproduce or prove browser scheduling across tabs and workers. Verify that behavior separately in real same-origin secure-context browser execution.
Working example
// This is an application-owned ordering wrapper. It does not emulate or prove
// browser Web Locks scheduling; run the same calls in same-origin browser tabs
// or workers to verify real navigator.locks behavior.
/**
* Returns the one global order used by every multi-resource operation.
* Duplicate names are rejected: requesting the same named lock twice is not a
* second independent resource acquisition.
*/
export function orderedResourceNames(resources) {
if (!Array.isArray(resources) || resources.length === 0) {
throw new TypeError("resources must be a non-empty array");
}
const names = resources.map((name) => {
if (typeof name !== "string" || name.length === 0) {
throw new TypeError("every resource name must be a non-empty string");
}
return name;
});
const ordered = [...names].sort();
for (let index = 1; index < ordered.length; index += 1) {
if (ordered[index] === ordered[index - 1]) {
throw new RangeError(`duplicate resource name: ${ordered[index]}`);
}
}
return ordered;
}
/**
* Acquires named locks in lexical order and runs work while every callback is
* still active. Each LockManager.request() releases its lock when its callback
* returns, so the nested callbacks are the critical-section boundary.
*
* With { ifAvailable: true }, a null lock prevents work from running and the
* already-entered callbacks return, releasing any earlier locks.
*/
export async function withOrderedLocks(lockManager, resources, work, options = {}) {
if (!lockManager || typeof lockManager.request !== "function") {
throw new TypeError("lockManager must provide request()");
}
if (typeof work !== "function") {
throw new TypeError("work must be a function");
}
const names = orderedResourceNames(resources);
async function acquire(index, heldLocks) {
if (index === names.length) {
return { acquired: true, value: await work(heldLocks) };
}
return lockManager.request(names[index], options, async (lock) => {
// Native Web Locks supplies null for an unavailable ifAvailable request.
if (lock === null) return { acquired: false };
return acquire(index + 1, [...heldLocks, lock]);
});
}
return acquire(0, []);
}
Read the full article: https://chriseugenerodriguez.com/blog/prevent-deadlocks-multiple-web-locks
Top comments (0)