Embind sakralny

Łączy ono kod JS z wasm.

Surma

W poprzednim artykule na temat formatu wasm omawiałem kompilowanie biblioteki C na potrzeby formatu wasm, aby można było z niej korzystać w internecie. Jedna rzecz, która rzucała się w oczy (i nie tylko mi, ale też wielu czytelnikom) to prymitywna i trochę niewygodna metoda ręcznego deklarowania funkcji modułu wasm, których używasz. Oto fragment kodu, o którym mówię:

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

Tutaj deklarujemy nazwy funkcji oznaczonych EMSCRIPTEN_KEEPALIVE, ich typy zwracanych wartości oraz typy argumentów. Następnie możemy użyć metod obiektu api do wywołania tych funkcji. Jednak używanie w ten sposób wasm nie obsługuje ciągów znaków i wymaga ręcznego przenoszenia fragmentów pamięci, co powoduje, że wiele interfejsów API bibliotek jest bardzo uciążliwe w użyciu. Czy nie ma lepszego sposobu? Oczywiście, bo inaczej nie byłoby tego artykułu.

nazwy funkcji w C++.

Chociaż wygodę programistów można uznać za wystarczający powód do stworzenia narzędzia ułatwiającego korzystanie z tych powiązań, istnieje też bardziej naglący powód: podczas kompilowania kodu C lub C++ każdy plik jest kompilowany osobno. Następnie kompilator łączy wszystkie te pliki obiektów i przekształca je w plik WASM. W języku C nazwy funkcji są nadal dostępne w pliku obiektowym, z którego korzysta linker. Aby wywołać funkcję C, wystarczy podać jej nazwę, którą przekazujemy jako ciąg znaków do funkcji cwrap().

Z drugiej strony, C++ obsługuje przeciążanie funkcji, co oznacza, że możesz zaimplementować tę samą funkcję kilka razy, o ile podpis jest inny (np. parametry o innym typie). Na poziomie kompilatora ładna nazwa, np. add, zostanie zmodyfikowana w taki sposób, aby kodować sygnaturę w nazwie funkcji dla linkera. W związku z tym nie będziemy już mogli znaleźć naszej funkcji po jej nazwie.

Uwaga: aby zapobiec przekształceniu nazw funkcji przez kompilator, możesz je opatrzyć adnotacjami za pomocą extern "C".

Wpisz embind

embind jest częścią zestawu narzędzi Emscripten i zawiera wiele makr C++, które umożliwiają adnotację kodu C++. Możesz zadeklarować, których funkcji, typów wartości, klas i typów wartości zamierzasz używać w JavaScript. Zacznijmy od prostych funkcji:

#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);
}

W porównaniu z poprzednim artykułem nie uwzględniamy już emscripten.h, ponieważ nie musimy już oznaczać funkcji za pomocą EMSCRIPTEN_KEEPALIVE. Zamiast tego mamy sekcję EMSCRIPTEN_BINDINGS, w której podajemy nazwy, pod którymi chcemy udostępniać nasze funkcje językowi JavaScript.

Uwaga: parametr dla makra EMSCRIPTEN_BINDINGS jest używany głównie w większych projektach, aby uniknąć konfliktów nazw.

Aby skompilować ten plik, możemy użyć tej samej konfiguracji (lub, jeśli chcesz, tego samego obrazu Dockera) co w poprzednim artykule. Aby użyć embind, dodaj flagę --bind:

$ emcc --bind -O3 add.cpp

Teraz wystarczy utworzyć plik HTML, który wczyta utworzony przez nas moduł WASM:

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

Uwaga: jeśli jesteś ciekaw, napisałem ten sam moduł C++ bez embind, aby pokazać, ile pracy wykonuje za Ciebie embind.

Jak widać, nie używamy już cwrap(). To działa od razu po zainstalowaniu. Co ważniejsze, nie musimy się martwić ręcznym kopiowaniem fragmentów pamięci, aby działały ciągi tekstowe. embind zapewnia to bezpłatnie, a także sprawdzanie typu:

To świetna rzecz, ponieważ możemy wcześnie wykrywać niektóre błędy, zamiast radzić sobie z błędami w plikach wasm, które czasami są dość trudne do opanowania.

Obiekty

Wiele konstruktorów i funkcji JavaScript używa obiektów opcji. To ładny wzór w JavaScriptzie, ale bardzo żmudny do zrealizowania ręcznie w wasm. W tym przypadku również może Ci pomóc embind.

Na przykład wymyśliłem niezwykle przydatną funkcję C++, która przetwarza moje ciągi znaków. Chcę jej pilnie użyć w internecie. Oto jak to zrobiłem:

#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);
}

Definiuję element struct dla opcji funkcji processMessage(). W bloku EMSCRIPTEN_BINDINGS mogę użyć funkcji value_object, aby JavaScript traktował tę wartość C++ jako obiekt. Jeśli wolisz użyć tej wartości C++ jako tablicy, możesz też użyć value_array. Funkcję processMessage() również wiążemy, a reszta to magia embind. Teraz mogę wywołać funkcję processMessage() z JavaScriptu bez żadnego kodu szablonowego:

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

Zajęcia

Dla porządku pokażę też, jak embind umożliwia udostępnianie całych klas, co sprzyja współpracy z klasami ES6. Zapewne zaczynasz już dostrzegać pewien wzór:

#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);
}

Po stronie JavaScriptu wygląda to prawie jak zwykła klasa:

<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>

A C?

Narzędzie embind zostało napisane dla języka C++ i może być używane tylko w plikach C++, ale nie oznacza to, że nie można tworzyć linków do plików C. Aby mieszać C i C++, wystarczy podzielić pliki wejściowe na 2 grupy: jedną dla plików C, a drugą dla plików C++ i uzupełnić flagi wiersza poleceń dla emcc w ten sposób:

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

Podsumowanie

embind znacznie ułatwia pracę deweloperom przy użyciu wasm i C/C++. Ten artykuł nie opisuje wszystkich opcji embind. Jeśli chcesz, zapoznaj się z dokumentacją embind. Pamiętaj, że użycie embind może spowodować zwiększenie rozmiaru skompresowanego pliku gzip zarówno modułu wasm, jak i kodu łączącego JavaScriptu nawet o 11 KB – szczególnie w przypadku małych modułów. Jeśli masz bardzo małą powierzchnię wasm, embind może kosztować więcej, niż jest to uzasadnione w środowisku produkcyjnym. Warto jednak spróbować.