Embind sakralny

Łączy JS z Wasm!

Surma

W poprzednim artykule omówiłem, jak skompilować bibliotekę C do biblioteki Wasm, aby można było z niej korzystać w internecie. Jedną z rzeczy, które zwróciły moją uwagę (i dla wielu czytelników) jest prymitywny i nieco niezręczny sposób, w jaki trzeba ręcznie zadeklarować, których funkcji modułu Wasm używasz. Dla przypomnienia – 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']),
};

W tym miejscu deklarujemy nazwy funkcji oznaczonych za pomocą atrybutu EMSCRIPTEN_KEEPALIVE, jakie są ich typy zwracanych i rodzaje argumentów. Później możemy wywoływać te funkcje przy użyciu metod w obiekcie api. Jednak korzystanie z Wasm w ten sposób nie obsługuje ciągów tekstowych i wymaga ręcznego przenoszenia fragmentów pamięci, co sprawia, że używanie wielu bibliotek bibliotecznych API jest bardzo żmudne. Czy nie ma lepszego sposobu? Dlaczego tak, a w przeciwnym razie o czym byłby ten artykuł?

Zarządzanie nazwami C++

Choć doświadczenie dla programistów wystarczy, by stworzyć narzędzie, które pomaga w ich reagowaniu, tak naprawdę istnieje ważniejsza przyczyna: gdy kompilujesz kod C lub C++, każdy plik jest kompilowany oddzielnie. Następnie łączy wszystkie tzw. pliki obiektów i przekształca je w plik Wasm. W przypadku C nazwy funkcji są nadal dostępne w pliku obiektów do użycia przez tag łączący. Aby móc wywołać funkcję C, wystarczy, że podasz jej nazwę, którą przekazujemy jako ciąg znaków funkcji cwrap().

Z kolei C++ obsługuje przeciążenie funkcji, co oznacza, że tę samą funkcję można zaimplementować wielokrotnie, z powodu innego podpisu (np. parametrów o innym wpisywaniu). Na poziomie kompilatora ładna nazwa, np. add, została zmienna w coś, co koduje podpis w nazwie funkcji tagu łączącego. W rezultacie nie będziemy mogli wyszukać naszej funkcji pod jej nazwą.

Uwaga: możesz uniemożliwić kompilatorowi modyfikowanie nazw funkcji, dodając do nich adnotacje extern "C".

Wpisz embind

embind to część łańcucha narzędzi Emscripten i udostępnia wiele makr C++, które umożliwiają dodawanie adnotacji do kodu w języku C++. W języku JavaScript możesz zadeklarować, które funkcje, wyliczenia, klasy lub typy wartości chcesz używać. 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 trzeba już dodawać adnotacji do funkcji EMSCRIPTEN_KEEPALIVE. Zamiast tego mamy sekcję EMSCRIPTEN_BINDINGS, w której wymieniamy nazwy, pod którymi chcemy udostępnić nasze funkcje dla JavaScriptu.

Uwaga: parametr makra EMSCRIPTEN_BINDINGS jest używany najczęściej do uniknięcia konfliktów nazw w większych projektach.

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

$ emcc --bind -O3 add.cpp

Teraz pozostaje wygenerować plik HTML, który wczytuje nasz nowo utworzony 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 ciekawi Cię, napisałam ten sam moduł C++ bez funkcji embindowania, aby dać Ci wyobrażenie o tym, ile pracy Ci on daje.

Jak widać, nie korzystamy już z usługi cwrap(). Działa to od razu po wyjęciu z pudełka. Co ważniejsze, nie musimy się przejmować ręcznym kopiowaniem fragmentów pamięci, aby ciągi tekstowe działały. Funkcja embind pozwala Ci to bezpłatnie wykonywać wraz z sprawdzaniem typu:

To świetnie, ponieważ jesteśmy w stanie wychwycić pewne błędy wcześniej, zamiast zajmować się czasami dość nieporęcznymi błędami Wasm.

Obiekty

Wiele konstruktorów i funkcji JavaScriptu korzysta z obiektów opcji. To ładny wzór w języku JavaScript, ale bardzo pracochłonne do samodzielnego wykonania w Wasm. Mogą też pomóc embind.

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

#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ć value_object, aby JavaScript podawał wartość z C++ jako obiekt. Mogę też użyć value_array, jeśli wolisz użyć tej wartości C++ jako tablicy. Powiążę też funkcję processMessage(), a reszta to magia. Mogę teraz wywołać funkcję processMessage() z poziomu JavaScriptu bez powtarzającego się kodu:

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

Zajęcia

Dla jasności pokażę Ci też, jak embind umożliwia odsłonięcie wszystkich zajęć, co zapewnia wiele synergii z klasami ES6. Teraz możesz już zauważyć pewne prawidłowości:

#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 klasa natywna:

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

Tag embind został napisany w języku C++ i można go używać tylko w plikach C++. Nie oznacza to jednak, że nie można tworzyć linków z plikami C. Aby połączyć pliki C i C++, wystarczy podzielić pliki wejściowe na 2 grupy: jedną dla plików C i jedną dla plików C++ oraz wzmocnić flagi interfejsu wiersza poleceń emcc w następujący sposób:

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

Podsumowanie

Usługa embind znacznie usprawnia pracę programistów w środowiskach Wasm i C/C++. W tym artykule nie omówiliśmy wszystkich opcji powiązanych z ofertami. Jeśli chcesz dowiedzieć się więcej, zapoznaj się z dokumentacją usługi embind. Pamiętaj, że użycie metody embind może spowodować, że zarówno moduł Wasm, jak i kod JavaScriptu (gzip) w kodzie gzip, będą większe nawet o 11 tys. – zwłaszcza w przypadku małych modułów. W przypadku bardzo małej powierzchni w środowisku produkcyjnym jej łączenie może kosztować więcej niż jest to warte. Tak czy inaczej, zdecydowanie warto spróbować.