LockManager: request() Methode

name

Ein Bezeichner für das Lock, das Sie anfordern möchten.

options Optional

Ein Objekt, das die Eigenschaften des Locks beschreibt, das Sie erstellen möchten. Gültige Werte sind:

mode Optional

Entweder "exclusive" oder "shared". Der Standardwert ist "exclusive".

ifAvailable Optional

Wenn true, wird die Lock-Anfrage nur gewährt, wenn sie nicht bereits gehalten wird. Wenn sie nicht gewährt werden kann, wird der Callback mit null anstelle einer Lock-Instanz aufgerufen. Der Standardwert ist false.

steal Optional

Wenn true, werden alle gehaltenen Locks mit demselben Namen freigegeben, und die Anfrage wird gewährt, wobei alle in der Warteschlange befindlichen Anfragen für sie ersetzt werden. Der Standardwert ist false.

Warnung: Mit Vorsicht verwenden! Code, der zuvor innerhalb des Locks ausgeführt wurde, läuft weiter und kann mit dem Code in Konflikt geraten, der jetzt das Lock hält.

signal Optional

Ein AbortSignal (die signal Eigenschaft eines AbortController); wenn angegeben und der AbortController wird abgebrochen, wird die Lock-Anfrage abgebrochen, wenn sie noch nicht gewährt wurde.

callback

Methode, die aufgerufen wird, wenn das Lock gewährt wird. Das Lock wird automatisch freigegeben, wenn der Callback zurückkehrt (oder eine Ausnahme ausgelöst wird). In der Regel ist der Callback eine asynchrone Funktion, die dazu führt, dass der Lock erst freigegeben wird, wenn die asynchrone Funktion vollständig abgeschlossen ist.

Ein Promise das auflöst (oder ablehnt) mit dem Ergebnis des Callbacks nach Freigabe des Locks oder ablehnt, wenn die Anfrage abgebrochen wird.

Diese Methode kann ein Promise zurückgeben, das mit einer DOMException einer der folgenden Arten abgelehnt wird:

InvalidStateError DOMException

Wird ausgelöst, wenn das Dokument der Umgebung nicht vollständig aktiv ist.

SecurityError DOMException

Wird ausgelöst, wenn für die aktuelle Umgebung kein Lock-Manager abgerufen werden kann.

NotSupportedError DOMException

Wird ausgelöst, wenn name mit einem Bindestrich (-) beginnt, sowohl die Optionen steal als auch ifAvailable true sind oder wenn die Option signal existiert und entweder die Option steal oder ifAvailable true ist.

AbortError DOMException

Wird ausgelöst, wenn die Option signal existiert und abgebrochen wird.

Das folgende Beispiel zeigt die grundlegende Verwendung der request() Methode mit einer asynchronen Funktion als Callback. Sobald der Callback aufgerufen wird, kann kein anderer laufender Code auf diesem Ursprung my_resource halten, bis der Callback zurückkehrt.

await navigator.locks.request("my_resource", async (lock) => {
  // The lock was granted.
});

Das folgende Beispiel zeigt, wie die mode-Option für Leser und Schreiber verwendet wird.

Beachtrichten, dass beide Funktionen ein Lock namens my_resource verwenden. Die do_read() fordert ein Lock im 'shared' Modus an, was bedeutet, dass mehrere Anrufe gleichzeitig über verschiedene Event-Handler, Tabs oder Worker erfolgen können.

async function do_read() {
  await navigator.locks.request(
    "my_resource",
    { mode: "shared" },
    async (lock) => {
      // Read code here.
    },
  );
}

Die do_write()-Funktion verwendet dasselbe Lock, jedoch im 'exclusive' Modus, was die Ausführung des request()-Aufrufs in do_read() verzögert, bis der Schreibvorgang abgeschlossen ist. Dies gilt für Event-Handler, Tabs oder Worker.

async function do_write() {
  await navigator.locks.request(
    "my_resource",
    { mode: "exclusive" },
    async (lock) => {
      // Write code here.
    },
  );
}

Um ein Lock nur zu erhalten, wenn es noch nicht gehalten wird, verwenden Sie die ifAvailable-Option. In dieser Funktion bedeutet await, dass die Methode nicht zurückkehrt, bis der Callback abgeschlossen ist. Da der Lock nur gewährt wird, wenn er verfügbar war, vermeidet dieser Aufruf das Warten auf die Freigabe des Locks an anderer Stelle.

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.
  },
);

Um nur für eine kurze Zeit auf ein Lock zu warten, verwenden Sie die 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.
  }
}