LockManager: request() method
The request()
method of the LockManager
interface requests a Lock
object with parameters specifying its name and characteristics. The requested Lock
is passed to a callback, while the function itself returns a Promise
that resolves (or rejects) with the result of the callback after the lock is released, or rejects if the request is aborted.
The mode
property of the options
parameter may be either "exclusive"
or "shared"
.
Request an "exclusive"
lock when it should only be held by one code instance at a time. This applies to code in both tabs and workers. Use this to represent mutually exclusive access to a resource. When an "exclusive"
lock for a given name is held, no other lock with the same name can be held.
Request a "shared"
lock when multiple instances of the code can share access to a resource. When a "shared"
lock for a given name is held, other "shared"
locks for the same name can be granted, but no "exclusive"
locks with that name can be held or granted.
This shared/exclusive lock pattern is common in database transaction architecture, for example to allow multiple simultaneous readers (each requests a "shared"
lock) but only one writer (a single "exclusive"
lock). This is known as the readers-writer pattern. In the IndexedDB API, this is exposed as "readonly"
and "readwrite"
transactions which have the same semantics.
Syntax
request(name, callback)
request(name, options, callback)
Parameters
name
-
An identifier for the lock you want to request.
-
options
Optional
-
An object describing characteristics of the lock you want to create. Valid values are:
-
mode
Optional
-
Either "exclusive"
or "shared"
. The default value is "exclusive"
.
-
ifAvailable
Optional
-
If true
, the lock request will only be granted if it is not already held. If it cannot be granted, the callback will be invoked with null
instead of a Lock
instance. The default value is false
.
-
steal
Optional
-
If true
, then any held locks with the same name will be released, and the request will be granted, preempting any queued requests for it. The default value is false
.
Warning: Use with care! Code that was previously running inside the lock continues to run, and may clash with the code that now holds the lock.
-
signal
Optional
-
An AbortSignal
(the signal
property of an AbortController
); if specified and the AbortController
is aborted, the lock request is dropped if it was not already granted.
callback
-
Method called when the lock is granted. The lock is automatically released when the callback returns (or an exception is thrown). Usually the callback is an async function, which causes the lock to be released only when the async function has completely finished.
Return value
A Promise
that resolves (or rejects) with the result of the callback after the lock is released, or rejects if the request is aborted.
Exceptions
This method may return a promise rejected with a DOMException
of one of the following types:
-
InvalidStateError
DOMException
-
If the environments document is not fully active.
-
SecurityError
DOMException
-
If a lock manager cannot be obtained for the current environment.
-
NotSupportedError
DOMException
-
If name
starts with a hyphen (-
), both options steal
and ifAvailable
are true
, or if option signal
exists and either option steal
or ifAvailable
is true
.
-
AbortError
DOMException
-
If the option signal
exists and is aborted.
Examples
General Example
The following example shows the basic use of the request()
method with an asynchronous function as the callback. Once the callback is invoked, no other running code on this origin can hold my_resource
until the callback returns.
await navigator.locks.request("my_resource", async (lock) => {
});
Mode Example
The following example shows how to use the mode
option for readers and writers.
Notice that both functions use a lock called my_resource
. The do_read()
requests a lock in 'shared'
mode meaning that multiple calls may occur simultaneously across different event handlers, tabs, or workers.
async function do_read() {
await navigator.locks.request(
"my_resource",
{ mode: "shared" },
async (lock) => {
},
);
}
The do_write()
function use the same lock but in 'exclusive'
mode which will delay invocation of the request()
call in do_read()
until the write operation has completed. This applies across event handlers, tabs, or workers.
async function do_write() {
await navigator.locks.request(
"my_resource",
{ mode: "exclusive" },
async (lock) => {
},
);
}
ifAvailable Example
To grab a lock only if it isn't already being held, use the ifAvailable
option. In this function await
means the method will not return until the callback is complete. Since the lock is only granted if it was available, this call avoids needing to wait on the lock being released elsewhere.
await navigator.locks.request(
"my_resource",
{ ifAvailable: true },
async (lock) => {
if (!lock) {
return;
}
},
);
signal Example
To only wait for a lock for a short period of time, use the signal
option.
const controller = new AbortController();
setTimeout(() => controller.abort(), 200);
try {
await navigator.locks.request(
"my_resource",
{ signal: controller.signal },
async (lock) => {
},
);
} catch (ex) {
if (ex.name === "AbortError") {
}
}
Specifications
Browser compatibility
|
Desktop |
Mobile |
|
Chrome |
Edge |
Firefox |
Internet Explorer |
Opera |
Safari |
WebView Android |
Chrome Android |
Firefox for Android |
Opera Android |
Safari on IOS |
Samsung Internet |
request |
69 |
79 |
96 |
No |
56 |
15.4 |
69 |
69 |
96 |
48 |
15.4 |
10.0 |