LockManager: request() Methode
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since March 2022.
Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.
Hinweis: Dieses Feature ist verfügbar in Web Workers.
Die request()
-Methode der LockManager
-Schnittstelle fordert ein Lock
-Objekt an, wobei Parameter dessen Namen und Eigenschaften spezifizieren.
Das angeforderte Lock
wird an eine Callback-Funktion übergeben, während die Funktion selbst ein Promise
zurückgibt, das mit dem Ergebnis des Callbacks aufgelöst (oder abgelehnt) wird, nachdem der Lock freigegeben wurde, oder abgelehnt wird, wenn die Anforderung abgebrochen wird.
Die mode
-Eigenschaft des options
-Parameters kann entweder "exclusive"
oder "shared"
sein.
Fordern Sie eine "exclusive"
-Sperre an, wenn sie nur von einer Code-Instanz zu einem Zeitpunkt gehalten werden sollte.
Dies gilt sowohl für Code in Registerkarten als auch in Workern. Verwenden Sie dies, um einen gegenseitig ausschließenden Zugriff auf eine Ressource zu repräsentieren.
Wenn eine "exclusive"
-Sperre für einen bestimmten Namen gehalten wird, kann keine andere Sperre mit demselben Namen gehalten werden.
Fordern Sie eine "shared"
-Sperre an, wenn mehrere Instanzen des Codes gemeinsam auf eine Ressource zugreifen können.
Wenn eine "shared"
-Sperre für einen bestimmten Namen gehalten wird, können andere "shared"
-Sperren für denselben Namen gewährt werden, aber keine "exclusive"
-Sperren mit diesem Namen können gehalten oder gewährt werden.
Dieses Muster von gemeinsamer/exklusiver Sperre ist in der Datenbank-Transaktionsarchitektur üblich, um zum Beispiel mehrere gleichzeitige Leser zuzulassen (jeder fordert eine "shared"
-Sperre an), aber nur einen Schreiber (eine einzelne "exclusive"
-Sperre).
Dies ist als das Leser-Schreiber-Muster bekannt.
Im IndexedDB API wird dies als "readonly"
und "readwrite"
-Transaktionen angezeigt, die dieselbe Semantik besitzen.
Syntax
request(name, callback)
request(name, options, callback)
Parameter
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 mitnull
anstelle einerLock
-Instanz ausgeführt. Der Standardwert istfalse
. 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 istfalse
.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
(diesignal
-Eigenschaft einesAbortController
); wenn angegeben und derAbortController
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.
Rückgabewert
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.
Ausnahmen
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 Optionensteal
als auchifAvailable
true
sind oder wenn diesignal
-Option vorhanden ist und entweder die Optionsteal
oderifAvailable
true
ist. AbortError
DOMException
-
Wird ausgelöst, wenn die Option
signal
vorhanden ist und abgebrochen wird.
Beispiele
Allgemeines Beispiel
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.
});
mode
Beispiel
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.
},
);
}
ifAvailable
Beispiel
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.
},
);
signal
Beispiel
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.
}
}
Spezifikationen
Specification |
---|
Web Locks API # api-lock-manager-request |
Browser-Kompatibilität
BCD tables only load in the browser