# 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly). ## 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 `Promise`que resolve para uma `Instance`desse `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.LinkError`objeto 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 `options`objeto. A `options.traceStack`propriedade 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 `stack`propriedade 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 `TypeError`exceção será lançada. `options` (opcional) Um objeto com os seguintes campos opcionais: `traceStack` (opcional) `true`se o `Exception`pode ter um rastreamento de pilha anexado à sua `stack`propriedade, caso contrário `false`. Isso é `false`por padrão (se `options`ou `options.traceStack`nã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]); ``` ---