LockManager: request() Methode

name

Ein Bezeichner für die Sperre, die Sie anfordern möchten.

options Optional

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

mode Optional

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

ifAvailable Optional

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

steal Optional

Wenn true, werden alle gehaltenen Sperren mit demselben Namen freigegeben und die Anforderung wird gewährt, wodurch alle dafür eingereihten Anfragen vorweggenommen werden. Der Standardwert ist false.

Warnung: Verwenden Sie dies mit Vorsicht! Code, der zuvor innerhalb der Sperre ausgeführt wurde, läuft weiter und kann mit dem Code in Konflikt geraten, der die Sperre jetzt hält.

signal Optional

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

callback

Methode, die aufgerufen wird, wenn die Sperre gewährt wird. Die Sperre wird automatisch freigegeben, wenn das Callback zurückkehrt (oder eine Ausnahme ausgelöst wird). In der Regel ist das Callback eine asynchrone Funktion, die dafür sorgt, dass die Sperre erst freigegeben wird, wenn die asynchrone Funktion vollständig beendet ist.

Ein Promise das mit dem Ergebnis des Callbacks aufgelöst (oder abgelehnt) wird, nachdem die Sperre freigegeben wurde, oder abgelehnt wird, wenn die Anforderung abgebrochen wird.

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

InvalidStateError DOMException

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

SecurityError DOMException

Wird ausgelöst, wenn ein Sperrenmanager für die aktuelle Umgebung nicht bezogen 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 signal-Option vorhanden ist und entweder die Option steal oder ifAvailable true ist.

AbortError DOMException

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

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

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

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

Beachten Sie, dass beide Funktionen eine Sperre namens my_resource verwenden. Die Funktion do_read() fordert eine Sperre im 'shared'-Modus an, was bedeutet, dass mehrere Aufrufe gleichzeitig über verschiedene Ereignishandler, Registerkarten oder Worker stattfinden können.

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

Die do_write()-Funktion verwendet dieselbe Sperre, jedoch im 'exclusive'-Modus, wodurch die Ausführung des request()-Aufrufs in do_read() verzögert wird, bis der Schreibvorgang abgeschlossen ist. Dies gilt über Ereignishandler, Registerkarten oder Worker hinweg.

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

Um eine Sperre nur zu erhalten, wenn sie nicht bereits gehalten wird, verwenden Sie die ifAvailable-Option. In dieser Funktion bedeutet await, dass die Methode erst zurückkehrt, wenn das Callback abgeschlossen ist. Da die Sperre nur gewährt wird, wenn sie verfügbar war, vermeidet dieser Aufruf, auf die Freigabe der Sperre an anderer Stelle warten zu müssen.

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 eine Sperre 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.
  }
}