WebAssembly.Memory() Konstruktor

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since October 2017.

Der WebAssembly.Memory() Konstruktor erstellt ein neues Memory-Objekt, dessen buffer-Eigenschaft ein anpassbares ArrayBuffer oder SharedArrayBuffer ist, das die rohen Bytes des Speichers hält, auf die von einer WebAssembly.Instance zugegriffen wird.

Ein Speicherobjekt, das durch JavaScript oder in WebAssembly-Code erstellt wurde, wird sowohl von JavaScript als auch von WebAssembly aus zugänglich und veränderbar sein, vorausgesetzt, dass der Code das Objekt erstellt hat oder das Objekt ihm übergeben wurde.

Sowohl WebAssembly als auch JavaScript können Memory-Objekte erstellen. Wenn Sie auf den in JS erstellten Speicher von Wasm aus zugreifen möchten oder umgekehrt, können Sie eine Referenz auf den Speicher von einer Seite zur anderen übergeben.

Syntax

js
new WebAssembly.Memory(memoryDescriptor)

Parameter

memoryDescriptor

Ein Objekt, das die folgenden Mitglieder enthalten kann:

initial

Die anfängliche Größe des WebAssembly-Speichers, in Einheiten von WebAssembly-Seiten.

maximum Optional

Die maximale Größe, auf die der WebAssembly-Speicher wachsen darf, in Einheiten von WebAssembly-Seiten. Wenn vorhanden, fungiert der maximum Parameter als Hinweis für die Engine, Speicher im Voraus zu reservieren. Die Engine kann diese Reservierungsanfrage jedoch ignorieren oder beschränken. Nicht-geteilte WebAssembly-Speicher müssen kein maximum festlegen, aber geteilte Speicher tun dies.

shared Optional

Ein boolescher Wert, der definiert, ob der Speicher ein geteilter ist oder nicht. Wenn auf true gesetzt, ist es ein geteilter Speicher. Standard ist false.

Hinweis: Eine WebAssembly-Seite hat eine konstante Größe von 65.536 Bytes, d.h. 64KiB.

Ausnahmen

TypeError

Wird ausgelöst, wenn mindestens eine dieser Bedingungen erfüllt ist:

  • memoryDescriptor ist kein Objekt.
  • initial ist nicht angegeben.
  • shared ist vorhanden und true, doch maximum ist nicht angegeben.
RangeError

Wird ausgelöst, wenn mindestens eine dieser Bedingungen erfüllt ist:

  • maximum ist angegeben und kleiner als initial.
  • initial überschreitet 65.536 (2^16). 2^16 Seiten ist 2^16 * 64KiB = 4GiB Bytes, was der maximale Bereich ist, den ein Wasm-Modul adressieren kann, da Wasm derzeit nur 32-Bit-Adressierung erlaubt.
  • Die Zuordnung schlägt fehl. Dies kann passieren, wenn versucht wird, zu viel auf einmal zuzuordnen, oder wenn der User Agent anderweitig keinen Speicher mehr hat.

Beispiele

Erstellen einer neuen Memory-Instanz

Es gibt zwei Möglichkeiten, ein WebAssembly.Memory-Objekt zu erhalten: es von JavaScript zu konstruieren oder es von einem WebAssembly-Modul exportieren zu lassen.

Das folgende Beispiel (siehe memory.html auf GitHub, und sehen Sie es auch live) erstellt eine neue WebAssembly-Memory-Instanz mit einer anfänglichen Größe von 10 Seiten (640KiB) und einer maximalen Größe von 100 Seiten (6.4MiB). Das Beispiel lädt und instanziiert den geladenen memory.wasm-Bytecode mit der Funktion WebAssembly.instantiateStreaming(), während es den in der obigen Zeile erstellten Speicher importiert. Es speichert dann einige Werte in diesem Speicher, exportiert eine Funktion und verwendet die exportierte Funktion, um diese Werte zu summieren. Die buffer-Eigenschaft des Memory-Objekts wird einen ArrayBuffer zurückgeben.

js
const memory = new WebAssembly.Memory({
  initial: 10,
  maximum: 100,
});

WebAssembly.instantiateStreaming(fetch("memory.wasm"), {
  js: { mem: memory },
}).then((obj) => {
  const summands = new DataView(memory.buffer);
  for (let i = 0; i < 10; i++) {
    summands.setUint32(i * 4, i, true); // WebAssembly is little endian
  }
  const sum = obj.instance.exports.accumulate(0, 10);
  console.log(sum);
});

Erstellen eines geteilten Speichers

Standardmäßig sind WebAssembly-Speicher ungeteilt. Sie können aus JavaScript heraus einen geteilten Speicher erstellen, indem Sie shared: true im Initialisierungsobjekt des Konstruktors übergeben:

js
const memory = new WebAssembly.Memory({
  initial: 10,
  maximum: 100,
  shared: true,
});

Die buffer-Eigenschaft dieses Speichers wird einen SharedArrayBuffer zurückgeben.

Spezifikationen

Specification
WebAssembly JavaScript Interface
# dom-memory-memory

Das shared-Attribut ist nur in dem Threading-Vorschlag für WebAssembly dokumentiert und nicht Teil der offiziellen Spezifikationen.

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch