JavaScript Runtime APIs - WebAssembly

Nota: Azion Functions Runtime oferece a interface do módulo WebAssembly, conforme definido pela MDN. Você pode revisar a documentação diretamente no site da MDN aqui.

1. WebAssembly – Static methods

1.1.WebAssembly.compile()

A função WebAssembly.compile() compila o código binário WebAssembly.module em um objeto WebAssembly.Module. Esta função é útil se for necessário compilar um módulo antes que ele possa ser instanciado (caso contrário, a função WebAssembly.instantiate() deve ser usada).

Sintaxe

WebAssembly.compile(bufferSource)

Parâmetros

bufferSource

Um typed array ou ArrayBuffer contendo o código binário do módulo .wasm que você deseja compilar.

Exemplo

fetch('http://url/simple.wasm').then(response =>
  response.arrayBuffer()
).then(bytes =>
  WebAssembly.compile(bytes)
).then(mod =>
  //your code here
);

1.2. WebAssembly.compileStreaming()

A função WebAssembly.compileStreaming() compila um WebAssembly.Module fdiretamente de uma fonte subjacente transmitida. Esta função é útil se for necessário compilar um módulo antes que ele possa ser instanciado (caso contrário, a função WebAssembly.instantiateStreaming() deve ser usada).

Sintaxe

WebAssembly.compileStreaming (source)

Parâmetros

source

Um objeto Response, representando a origem subjacente de um módulo .wasm que você deseja transmitir e compilar.

Exemplo

var importObject = { imports: { imported_func: arg => console.log(arg) } };


WebAssembly.compileStreaming(fetch('http://url/simple.wasm'))
.then(module => WebAssembly.instantiate(module, importObject))
.then(instance => instance.exports.exported_func());

1.3. WebAssembly.instantiate()

Uma função WebAssembly.instantiate() permite compilar e instanciar código WebAssembly. Esta função tem dois overloads:

  • O overload primário usa o código binário do WebAssembly, na forma de uma typed array ou ArrayBuffer, e executa a compilação e a instanciação em uma única etapa;
  • O overload secundário usa um WebAssembly.Module já compilado e retorna uma Promiseque resolve para uma Instancedesse Module.

Sintaxe (overload primário)

WebAssembly.instantiate(bufferSource, importObject);

Parâmetros

bufferSource

Um typed array ou ArrayBuffer contendo o código binário do módulo .wasm que você deseja compilar.

importObject (opcional)

Um objeto contendo os valores a serem importados para a Instance recém criada, tais como funções ou objetos WebAssembly.Memory. Deve haver uma propriedade correspondente para cada importação declarada do módulo compilado ou então um WebAssembly.LinkError é apresentado.

Exemplo

var importObject = {
  imports: {
    imported_func: function(arg) {
      console.log(arg);
    }
  }
};


fetch('http://url/simple.wasm').then(response =>
  response.arrayBuffer()
).then(bytes =>
  WebAssembly.instantiate(bytes, importObject)
).then(result =>
  result.instance.exports.exported_func()
);

Sintaxe (overload secundário)

WebAssembly.instantiate(module, importObject);

Parâmetros

module

O objeto WebAssembly.Module a ser instanciado.

importObject (opcional)

Um objeto contendo os valores a serem importados para a Instance recém criada, tais como funções ou objetos WebAssembly.Memory. Deve haver uma propriedade correspondente para cada importação declarada do módulo compilado ou então um WebAssembly.LinkError é apresentado.

Exemplo

WebAssembly.compileStreaming(fetch('http://url/simple.wasm'))
.then(module => WebAssembly.instantiate(module))
.then(instance => instance.exports.exported_func());

1.4. WebAssembly.instantiateStreaming()

A função WebAssembly.instantiateStreaming() compila e instancia um módulo WebAssembly diretamente de uma fonte subjacente transmitida. Essa é a maneira mais eficiente e otimizada de carregar o código wasm.

Sintaxe

WebAssembly.instantiateStreaming(source, importObject)

Parâmetros

source

Um objeto Response ou uma promessa que será cumprida com um, representando a fonte subjacente de um módulo .wasm que você deseja transmitir, compilar e instanciar.

importObject (opcional)

An object containing the values to be imported into the newly-created Instance, such as functions or WebAssembly.Memory objects. There must be one matching property for each declared import of the compiled module or else a WebAssembly.LinkError is thrown.

Um objeto contendo os valores a serem importados para a Instance recém criada, tais como funções ou objetos WebAssembly.Memory. Deve haver uma propriedade correspondente para cada importação declarada do módulo compilado ou então um WebAssembly.LinkError é apresentado.

Exemplo

var importObject = { imports: { imported_func: arg => console.log(arg) } };


WebAssembly.instantiateStreaming(fetch('http://url/simple.wasm'), importObject)
.then(obj => obj.instance.exports.exported_func());

1.5. WebAssembly.validate()

A função WebAssembly.validate() valida um determinado typed array de código binário WebAssembly, retornando se os bytes formam um módulo wasm válido ( true) ou não ( false).

Sintaxe

WebAssembly.validate(bufferSource)

Parâmetros

bufferSource

Um typed array ou ArrayBuffer contendo código binário WebAssembly a ser validado.

Exemplo

fetch('http://url/simple.wasm').then(response =>
  response.arrayBuffer()
).then(function(bytes) {
  const valid = WebAssembly.validate(bytes);
  console.log("The given bytes are "
    + (valid ? "" : "not ") + "a valid wasm module");
});

2. WebAssembly - Constructor properties

2.1. WebAssembly.CompileError() constructor

O objeto WebAssembly.CompileError() indica um erro durante a decodificação ou validação do WebAssembly.

Sintaxe

new WebAssembly.CompileError()

new WebAssembly.CompileError(message)

new WebAssembly.CompileError(message, fileName)

new WebAssembly.CompileError(message, fileName, lineNumber)

Parâmetros

message (opcional)

Descrição legível do erro (human-readable).

fileName (opcional)

O nome do arquivo que contém o código que causou o erro.

lineNumber (opcional)

O número de linha do código que causou o erro.

Exemplo

try {
  throw new WebAssembly.CompileError('Hello', 'someFile', 10);
} catch (e) {
  console.log(e instanceof CompileError); // true
  console.log(e.message);                 // "Hello"
  console.log(e.name);                    // "CompileError"
  console.log(e.fileName);                // "someFile"
  console.log(e.lineNumber);              // 10
  console.log(e.columnNumber);            // 0
  console.log(e.stack);                   // returns the location where the code was run
}

2.2. WebAssembly.Instance() constructor

O WebAssembly.Instance() cria um novo objeto Instance que é uma instância executável com estado de um WebAssembly.Module.

Sintaxe

new WebAssembly.Instance(module, importObject)

Parâmetros

module

O objeto WebAssembly.Module a ser instanciado.

importObject (opcional)

Um objeto que contém os valores a serem importados para a Instance recém criada, como funções ou objetos WebAssembly.Memory.

Exemplo

const importObject = {
  imports: {
    imported_func: function(arg) {
      console.log(arg);
    }
  }
};


fetch('http://url/simple.wasm').then(response =>
  response.arrayBuffer()
).then(bytes => {
  let mod = new WebAssembly.Module(bytes);
  let instance = new WebAssembly.Instance(mod, importObject);
  instance.exports.exported_func();
})

2.3. WebAssembly.LinkError() constructor

O WebAssembly.LinkErrorobjeto indica um erro durante a instanciação do módulo (além de armadilhas da função start). Sintaxe

new WebAssembly.LinkError()

new WebAssembly.LinkError(message)

new WebAssembly.LinkError(message, fileName)

new WebAssembly.LinkError(message, fileName, lineNumber)

Parâmetros

message (opcional)

Descrição legível do erro (human-readable).

fileName (opcional)

O nome do arquivo que contém o código que causou o erro.

lineNumber (opcional)

O número de linha do código que causou o erro.

Examples

try {
  throw new WebAssembly.LinkError('Hello', 'someFile', 10);
} catch (e) {
  console.log(e instanceof LinkError); // true
  console.log(e.message);                 // "Hello"
  console.log(e.name);                    // "LinkError"
  console.log(e.fileName);                // "someFile"
  console.log(e.lineNumber);              // 10
  console.log(e.columnNumber);            // 0
  console.log(e.stack);                   // returns the location where the code was run
}

2.4. WebAssembly.Memory() constructor

O WebAssembly.Memory() cria um novo objeto Memory cuja propriedade buffer é um ArrayBuffer ou SharedArrayBuffer redimensionável que contém os bytes brutos de memória acessados por uma instância WebAssembly.

Uma memória criada por JavaScript ou em código WebAssembly será acessível e mutável de JavaScript e WebAssembly.

Sintaxe

new WebAssembly.Memory(memoryDescriptor)

Parâmetros

memoryDescriptor

Um objeto que pode conter os seguintes elementos:

  • initial

    O tamanho inicial da WebAssembly Memory, em unidades de páginas WebAssembly.

  • maximum opcional

    O tamanho máximo que a WebAssembly Memory pode atingir, em unidades de páginas do WebAssembly. Quando presente, o parâmetro máximo atua como uma dica para o sistema reservar memória antecipadamente. No entanto, o mecanismo pode ignorar ou bloquear essa solicitação de reserva. As memórias não compartilhadas do WebAssembly não precisam definir um máximo, mas as memórias compartilhadas sim.

  • shared opcional

    Um valor booleano que define se a memória é compartilhada ou não. Se definido como true, é uma memória compartilhada. O padrão é false.

Exemplos

Criando uma nova Memory instance

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

Criando uma memória compartilhada

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

2.5. WebAssembly.Module() constructor

Um objeto WebAssembly.Module() cria um novo objeto Module contendo código WebAssembly sem estado que já foi compilado pelo navegador e pode ser compartilhado eficientemente com Workers e instanciado várias vezes.

A função WebAssembly.Module() pode ser chamada para compilar de forma síncrona determinado código binário WebAssembly. No entanto, a principal maneira de obter um módulo é por meio de uma função de compilação assíncrona como WebAssembly.compile().

Sintaxe

new WebAssembly.Module(bufferSource)

Parâmetros

bufferSource

Um typed array ou ArrayBuffer contendo o código binário do módulo .wasm que você deseja compilar.

Exemplo

const importObject = {
  imports: {
    imported_func: function(arg) {
      console.log(arg);
    }
  }
};


function createWasmModule(bytes) {
  return new WebAssembly.Module(bytes);
}


fetch('http://url/simple.wasm').then(response =>
  response.arrayBuffer()
).then(bytes => {
  let mod = createWasmModule(bytes);
  WebAssembly.instantiate(mod, importObject)
  .then(result =>
     result.exports.exported_func()
  );
})

2.6. WebAssembly.RuntimeError() constructor

O WebAssembly.RuntimeError() cria um novo objeto WebAssembly RuntimeError – o tipo que é lançado sempre que o WebAssembly especifica uma armadilha (trap).

Sintaxe

new WebAssembly.RuntimeError()

new WebAssembly.RuntimeError(message)

new WebAssembly.RuntimeError(message, fileName)

new WebAssembly.RuntimeError(message, fileName, lineNumber)

Parâmetros

message (opcional)

Descrição legível do erro (human-readable).

fileName (opcional)

O nome do arquivo que contém o código que causou o erro.

lineNumber (opcional)

O número de linha do código que causou o erro.

Example

try {
  throw new WebAssembly.RuntimeError('Hello', 'someFile', 10);
} catch (e) {
  console.log(e instanceof WebAssembly.RuntimeError); // true
  console.log(e.message);                             // "Hello"
  console.log(e.name);                                // "RuntimeError"
  console.log(e.fileName);                            // "someFile"
  console.log(e.lineNumber);                          // 10
  console.log(e.columnNumber);                        // 0
  console.log(e.stack);                               // returns the location where the code was run
}

2.7. WebAssembly.Table() constructor

O WebAssembly.Table() cria um novo objeto Table do tamanho e tipo de elemento fornecidos.

Sintaxe

new WebAssembly.Table(tableDescriptor)

Parâmetros

tableDescriptor

Um objeto que pode conter os seguintes elementos:

  • element

    Uma string representando o tipo de valor a ser armazenado na tabela. Isso pode ter um valor de “anyfunc” (funções) ou “externref” (referências de host).

  • initial

    O número inicial de elementos da WebAssembly Table.

  • maximum opcional

    O número máximo de elementos a que a WebAssembly Table é permitida expandir.

Example

var tbl = new WebAssembly.Table({initial:2, element:"anyfunc"});
var len = tbl.length;  // "2"
var v1 = tbl.get(0);  // "null"
var v2 = tbl.get(1);  // "null"


// Creating an import object that contains the table
var importObj = {
  js: {
    tbl:tbl
  }
};

2.8. WebAssembly.Tag() constructor

O WebAssembly.Tag() cria um novo objeto WebAssembly.Tag.

Sintaxe

new WebAssembly.Tag(type)

Parâmetros

type

Um objeto que pode conter os seguintes elementos:

  • parameters

    Um array de tipos de dados(“i32”, “i64”, “f32”, “f64”, “v128”, “externref”, “anyfunc”).

Exceções

TypeError

O argumento type.parameters não é fornecido, não contém pelo menos um valor ou contém um descritor de tag não suportado.

Exemplo

Isso cria uma tag com dois valores:

const tag = new WebAssembly.Tag({ parameters: ["i32", "i64"] });

2.9. WebAssembly.Exception constructor

O WebAssembly.Exception() é usado para criar um novo WebAssembly.Exception.

O construtor aceita um argumento Tag e um payload array de campos de dados. Os tipos de dados de cada um dos elementos de payload devem corresponder ao tipo de dados correspondente especificado na Tag.

O construtor também pode receber um optionsobjeto. A options.traceStackpropriedade pode ser definida como true (por padrão é false) para indicar que o código WebAssembly que lança a exceção pode preencher a stackpropriedade da exceção com uma stack track.

Sintaxe

new Exception(tag, payload, options)

Parâmetros

tag

Uma WebAssembly.Tag definição dos tipos de dados esperados para cada um dos valores no arquivo payload.

payload

Um array de um ou mais campos de dados compreendendo a carga útil da exceção. Os elementos devem corresponder aos tipos de dados dos elementos correspondentes no arquivo tag. Se o número de campos de dados na carga útil e seus tipos não corresponderem, uma TypeErrorexceção será lançada.

options (opcional)

Um objeto com os seguintes campos opcionais:

traceStack (opcional)

truese o Exceptionpode ter um rastreamento de pilha anexado à sua stackpropriedade, caso contrário false. Isso é falsepor padrão (se optionsou options.traceStacknão for fornecido).

Exceções

TypeError

As sequências payload e tag não têm o mesmo número de elementos e/ou os elementos não são de tipos correspondentes.

Exemplo

// Create tag and use it to create an exception
const tag = new WebAssembly.Tag({ parameters: ["i32", "f32"] });
const exception = new WebAssembly.Exception(tag, [42, 42.3]);

Contribuidores