Emscripten

Ele vincula o JS ao seu wasm.

Surma

No meu último artigo sobre wasm, falei sobre como compilar uma biblioteca C para wasm para que você possa usá-la na Web. Uma coisa que se destacou para mim (e para muitos leitores) é a maneira grosseira e um pouco constrangedora de declarar manualmente quais funções do módulo Wasm você está usando. Para refrescar sua memória, este é o snippet de código:

const api = {
    version: Module.cwrap('version', 'number', []),
    create_buffer: Module.cwrap('create_buffer', 'number', ['number', 'number']),
    destroy_buffer: Module.cwrap('destroy_buffer', '', ['number']),
};

Aqui declaramos os nomes das funções marcadas com EMSCRIPTEN_KEEPALIVE, os tipos de retorno e os tipos dos argumentos. Em seguida, podemos usar os métodos no objeto api para invocar essas funções. No entanto, o uso do WASM dessa forma não oferece suporte a strings e exige que você mova manualmente os pedaços de memória, o que torna muitas APIs de biblioteca muito cansativas de usar. Não existe uma maneira melhor? Por que sim. Caso contrário, sobre o que seria este artigo?

Mangling de nomes C++

Embora a experiência do desenvolvedor seja motivo suficiente para criar uma ferramenta que ajude com essas vinculações, há um motivo mais urgente: quando você compila código C ou C++, cada arquivo é compilado separadamente. Em seguida, um vinculador se encarrega de unir todos esses arquivos de objetos chamados e transformá-los em um arquivo Wasm. Com C, os nomes das funções ainda estão disponíveis no arquivo de objeto para uso pelo vinculador. Tudo o que você precisa para chamar uma função C é o nome, que estamos fornecendo como uma string para cwrap().

O C++ oferece suporte à sobrecarga de funções, o que significa que você pode implementar a mesma função várias vezes, desde que a assinatura seja diferente (por exemplo, parâmetros de tipos diferentes). No nível do compilador, um nome legal como add seria modificado em algo que codifica a assinatura no nome da função para o vinculador. Como resultado, não poderíamos mais procurar nossa função com o nome dela.

Observação : é possível impedir que o compilador manipule os nomes das funções anotando-as com extern "C".

Entrar em embind

O embind faz parte do conjunto de ferramentas Emscripten e fornece várias macros C++ que permitem anotar o código C++. Você pode declarar quais funções, tipos enumerados, classes ou tipos de valor planeja usar no JavaScript. Vamos começar com algumas funções simples:

#include <emscripten/bind.h>

using namespace emscripten;

double add(double a, double b) {
    return a + b;
}

std::string exclaim(std::string message) {
    return message + "!";
}

EMSCRIPTEN_BINDINGS(my_module) {
    function("add", &add);
    function("exclaim", &exclaim);
}

Em comparação com o artigo anterior, não estamos mais incluindo emscripten.h, já que não precisamos mais anotar nossas funções com EMSCRIPTEN_KEEPALIVE. Em vez disso, temos uma seção EMSCRIPTEN_BINDINGS em que listamos os nomes sob os quais queremos expor nossas funções ao JavaScript.

Observação : o parâmetro da macro EMSCRIPTEN_BINDINGS é usado principalmente para evitar conflitos de nome em projetos maiores.

Para compilar esse arquivo, podemos usar a mesma configuração (ou, se você quiser, a mesma imagem do Docker) do artigo anterior. Para usar o embind, adicione a flag --bind:

$ emcc --bind -O3 add.cpp

Agora, basta criar um arquivo HTML que carregue nosso módulo wasm recém-criado:

<script src="/a.out.js"></script>
<script>
Module.onRuntimeInitialized = _ => {
    console.log(Module.add(1, 2.3));
    console.log(Module.exclaim("hello world"));
};
</script>

Observação: escrevi o mesmo módulo C++ sem embind para que você tenha uma ideia de quanto trabalho ele está fazendo.

Como você pode ver, não estamos mais usando cwrap(). Isso funciona imediatamente. Mais importante, não precisamos nos preocupar em copiar manualmente blocos de memória para fazer as strings funcionarem. O embind oferece isso sem custo financeiro, junto com as verificações de tipo:

Isso é ótimo, porque podemos detectar alguns erros mais cedo, em vez de lidar com os erros do Wasm ocasionalmente complexos.

Objetos

Muitos construtores e funções do JavaScript usam objetos de opções. É um padrão legal em JavaScript, mas extremamente tedioso de realizar manualmente no WASM. O embind também pode ajudar aqui.

Por exemplo, criei essa função C++ incrivelmente útil que processa minhas strings e quero usá-la com urgência na Web. Eu fiz isso da seguinte forma:

#include <emscripten/bind.h>
#include <algorithm>

using namespace emscripten;

struct ProcessMessageOpts {
    bool reverse;
    bool exclaim;
    int repeat;
};

std::string processMessage(std::string message, ProcessMessageOpts opts) {
    std::string copy = std::string(message);
    if(opts.reverse) {
    std::reverse(copy.begin(), copy.end());
    }
    if(opts.exclaim) {
    copy += "!";
    }
    std::string acc = std::string("");
    for(int i = 0; i < opts.repeat; i++) {
    acc += copy;
    }
    return acc;
}

EMSCRIPTEN_BINDINGS(my_module) {
    value_object<ProcessMessageOpts>("ProcessMessageOpts")
    .field("reverse", &ProcessMessageOpts::reverse)
    .field("exclaim", &ProcessMessageOpts::exclaim)
    .field("repeat", &ProcessMessageOpts::repeat);

    function("processMessage", &processMessage);
}

Estou definindo um struct para as opções da minha função processMessage(). No bloco EMSCRIPTEN_BINDINGS, posso usar value_object para fazer o JavaScript ver esse valor C++ como um objeto. Também poderia usar value_array se preferisse usar esse valor C++ como uma matriz. Também vinculo a função processMessage(), e o restante é mágico. Agora, posso chamar a função processMessage() do JavaScript sem nenhum código boilerplate:

console.log(Module.processMessage(
    "hello world",
    {
    reverse: false,
    exclaim: true,
    repeat: 3
    }
)); // Prints "hello world!hello world!hello world!"

Classes

Para garantir a integridade, também preciso mostrar como o embind permite que você exponha classes inteiras, o que traz muita sinergia com as classes ES6. Provavelmente, você já começou a notar um padrão:

#include <emscripten/bind.h>
#include <algorithm>

using namespace emscripten;

class Counter {
public:
    int counter;

    Counter(int init) :
    counter(init) {
    }

    void increase() {
    counter++;
    }

    int squareCounter() {
    return counter * counter;
    }
};

EMSCRIPTEN_BINDINGS(my_module) {
    class_<Counter>("Counter")
    .constructor<int>()
    .function("increase", &Counter::increase)
    .function("squareCounter", &Counter::squareCounter)
    .property("counter", &Counter::counter);
}

Do lado do JavaScript, isso quase parece uma classe nativa:

<script src="/a.out.js"></script>
<script>
Module.onRuntimeInitialized = _ => {
    const c = new Module.Counter(22);
    console.log(c.counter); // prints 22
    c.increase();
    console.log(c.counter); // prints 23
    console.log(c.squareCounter()); // prints 529
};
</script>

E C?

O embind foi escrito para C++ e só pode ser usado em arquivos C++, mas isso não significa que não é possível vincular arquivos C. Para misturar C e C++, basta separar os arquivos de entrada em dois grupos: um para C e outro para C++ e aumentar as flags da CLI para emcc da seguinte maneira:

$ emcc --bind -O3 --std=c++11 a_c_file.c another_c_file.c -x c++ your_cpp_file.cpp

Conclusão

O embind oferece grandes melhorias na experiência do desenvolvedor ao trabalhar com wasm e C/C++. Este artigo não aborda todas as opções oferecidas pelo embind. Se você tiver interesse, recomendo continuar com a documentação do embind. Lembre-se de que o uso do embind pode aumentar o módulo Wasm e o código agrupador JavaScript em até 11k quando o gzip é aplicado, principalmente em módulos pequenos. Se você tiver apenas uma superfície de WASM muito pequena, o embind poderá custar mais do que o valor em um ambiente de produção. No entanto, você precisa experimentar.