Маршалинг во время выполнения

Каждый метод плагина — нативная функция с соглашением о вызовах C данной платформы. Маршалинг — то, что делает языковой модуль, чтобы превратить значения своего языка в аргументы такой функции и обратно. На этой странице перечислены типы, правила передачи и генераторы кода, которые ядро даёт модулям.

Типы

На 32-битных платформах тип указателя называется ptr32. Параметр с enum передаётся как его целый тип.

Полный список типов с именами в C++:

Возвращаемые значения

Небольшие значения возвращаются в регистрах. Более крупные записываются в память, которую выделяет вызывающий; она передаётся скрытым первым аргументом:

• всегда для string, any, всех массивов и mat4x4;
• для vec3 и vec4 на Windows; на Linux и macOS (x86-64 System V и ARM64) они возвращаются в регистрах.

vec2 и все скаляры везде возвращаются в регистрах. JitCallback и JitCall учитывают это сами; это важно, только если нативный код пишется вручную.

Контейнеры plg

plg::string, plg::vector, plg::any и векторные типы взяты из заголовков ядра (include/plg/). Их устройство в памяти одинаково, каким бы компилятором и стандартной библиотекой ни был собран модуль, поэтому через границу между плагинами передаются они, а не std::string или std::vector. Модуль может создавать и уничтожать их в своём C++-коде, а языку отдавать только указатели и простые данные. Языки, которые не умеют вызывать конструкторы C++, описывают то же устройство своими средствами, например пакеты плагинов для C#, Go и Rust.

Генерация функций во время выполнения

В ядре есть два генератора кода на asmjit. Они входят в библиотеку plugify, линковать ничего дополнительно не нужно. Оба работают по Method, описанию сигнатуры из манифеста, поэтому учитывают соглашение о вызовах, скрытый аргумент для возврата и ref-параметры метода.

Сгенерированная функция живёт столько же, сколько создавший её объект JitCallback или JitCall, поэтому храните эти объекты, пока функцию могут вызвать.

JitCallback

using CallbackHandler = void (*)(
    const Method* method,  // the signature
    Address data,          // the value passed to GetJitFunc
    uint64_t* params,      // one 64-bit slot per argument
    size_t count,          // number of slots
    void* ret              // where to write the return value
);

Address GetJitFunc(const Method& method, CallbackHandler callback, Address data = nullptr,
                   HiddenParam hidden = &ValueUtils::IsHiddenParam);

Каждый аргумент занимает один слот. Скаляры хранятся в самом слоте; строки, массивы, векторы и ref-параметры хранятся как указатели. ParametersSpan и ReturnSlot читают и пишут слоты:

// The handler behind a method `int32 Add(int32 a, int32 b)`
static void InternalCall(const Method* method, Address data, uint64_t* p, size_t count, void* r) {
    ParametersSpan params(p, count);
    ReturnSlot ret(r, sizeof(int32_t));
    int32_t a = params.Get<int32_t>(0);
    int32_t b = params.Get<int32_t>(1);
    ret.Set<int32_t>(a + b);
}

JitCallback callback;
Address func = callback.GetJitFunc(method, &InternalCall, userData);
if (!func) {
    // callback.GetError() says why
}

data обычно указывает на объект вашего языка, реализующий метод, например функцию Python, так что один обработчик обслуживает все методы. Если метод возвращает объект через скрытый аргумент, p[0] — память, в которой нужно сконструировать результат; для этого есть ReturnSlot::Construct<T>().

JitCall

using CallingFunc = void (*)(const uint64_t* params, const Return* ret);

Address GetJitFunc(const Method& method, Address target, WaitType waitType = WaitType::None,
                   HiddenParam hidden = &ValueUtils::IsHiddenParam);

Заполните Parameters, по одному значению на аргумент, вызовите сгенерированную функцию и прочитайте результат из Return:

// Call `int32 Add(int32 a, int32 b)` of another plugin
JitCall call;
Address func = call.GetJitFunc(method, target);

Parameters params(2);
params.Add(int32_t{ 2 }).Add(int32_t{ 3 });

Return ret;
func.As<JitCall::CallingFunc>()(params.Get(), &ret);
int32_t sum = ret.Get<int32_t>();  // 5

Для аргумента string добавьте указатель на plg::string; для метода, который возвращает string, первым аргументом добавьте указатель на память для результата и ничего в ней не конструируйте: это сделает вызываемая функция. WaitType::Breakpoint и WaitType::Wait_Keypress останавливаются перед вызовом, это помогает при отладке модуля.

Соглашения о вызовах и методы с переменным числом аргументов

По умолчанию методы используют соглашение о вызовах C данной платформы. Поле callConv метода в манифесте задаёт другое (cdecl, stdcall, fastcall, vectorcall, thiscall, x64systemv, x64windows и другие) для кода, которому оно нужно. varIndex — индекс первого параметра переменной части. Оба учитываются JitCall и JitCallback; нативные языки вызывают такие функции напрямую.

Советы

• Вызовы между двумя плагинами одного языка могут обходиться без маршалинга: модуль знает обе стороны и может вызвать код плагина напрямую, как это делает C#-модуль для C#-плагинов.
• Создавайте объекты JitCallback и JitCall один раз, при загрузке или экспорте плагина, а не при каждом вызове.
• Значение function, полученное от другого плагина, — просто адрес. Чтобы вызвать его из своего языка, сгенерируйте для него JitCall по prototype параметра.
• Проверяйте модуль cross-call тестами, см. Создание языкового модуля.