LockManager: request() method

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.

A Promise that resolves (or rejects) with the result of the callback after the lock is released, or rejects if the request is aborted.

This method may return a promise rejected with a DOMException of one of the following types:

InvalidStateError DOMException

Thrown if the environments document is not fully active.

SecurityError DOMException

Thrown if a lock manager cannot be obtained for the current environment.

NotSupportedError DOMException

Thrown 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

Thrown if the option signal exists and is aborted.

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) => {
  // The lock was granted.
});

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) => {
      // Read code here.
    },
  );
}

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) => {
      // Write code here.
    },
  );
}

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) {
      // The lock was not granted - get out fast.
      return;
    }

    // The lock was granted, and no other running code in this origin is holding
    // the 'my_res_lock' lock until this returns.
  },
);

To only wait for a lock for a short period of time, use the signal option.

const controller = new AbortController();
// Wait at most 200ms.
setTimeout(() => controller.abort(), 200);

try {
  await navigator.locks.request(
    "my_resource",
    { signal: controller.signal },
    async (lock) => {
      // The lock was acquired!
    },
  );
} catch (ex) {
  if (ex.name === "AbortError") {
    // The request aborted before it could be granted.
  }
}