Сучасна проблема Java і С++ або чому в Project Panama досі немає С++ інтеграції

💡 Усі статті, обговорення, новини про Java — в одному місці. Приєднуйтесь до Java спільноти!

Від автора

Всім привіт! Мене звати Денис Макогон. Я є cloud-архітектором і членом команди Java Developer Relations в Oracle. У своїй повсякденній роботі я багато стикаюся з рішеннями, написаними мовами, «не рекомендованими» АНБ для використання, — C, C++. І час від часу я займаюся саме створенням «middleware»-технологій-фреймворків, побудованих на основі Project Panama, які поєднують нативний код і Java, як, наприклад, ось така бібліотека.

У попередніх матеріалах про Project Panama ми вже говорили про Foreign Function & Memory (FFM) API (1, 2, 3, 4). З того часу FFM API встиг перейти з preview у стандартний API разом із релізом Java 22, а питання «чому б просто не зробити так, щоб jextract зчитував усе з C++ header-файлу?!» нікуди не зникло.

Цього разу хочу розібрати, у чому ж складність використання C++ коду в Java-застосунках. Ми розберемо усі аспекти детально, тож беріть каву і погнали.

Project Panama: що саме він вирішує

Project Panama — це великий напрямок в OpenJDK, який робить взаємодію Java з нативним кодом природнішою і більш зручною, аніж JNI. Для цього «deep-dive»-у важливі дві його частини:

• Foreign Function & Memory API: Java API для виклику нативних функцій і безпечнішої роботи з пам’яттю поза Java heap (аніж sun.misc.Unsafe);
• jextract: (JDK code tools) генератор Java-коду за C header-файлом, що створює однозначне відображення C-коду в Java code (враховуючи всі аспекти і експортовані символи: макроси, функції, структури, масиви і так далі, тобто все що експортується).

FFM API дає доступ до наступних класів: Linker, FunctionDescriptor, MemoryLayout, MemorySegment та Arena. Тобто за допомогою цього API на Java можна описати приблизно наступне: у «зовнішній бібліотеці» (.so, .dll, .dylib) знайти функцію з певною назвою, відповідним порядком і кількістю аргументів, певним return type і відповідною calling convention (стосується функцій із варіативною кількістю аргументів як, наприклад, сімейство функцій C fprintf) — і як результат отримати MethodHandle для її виклику.

Наприклад, для класичного C API на кшталт strlen низькорівневий варіант виглядає так:

import java.lang.foreign.*;
import java.lang.invoke.MethodHandle;

void main(String[] args) {
    var linker = Linker.nativeLinker();
    var strlen = linker.defaultLookup()
            .find("strlen")
            .orElseThrow();

    var strlenHandle = linker.downcallHandle(
            strlen, FunctionDescriptor.of(ValueLayout.JAVA_LONG, ValueLayout.ADDRESS)
    );

    try (var arena = Arena.ofConfined()) {
        var text = arena.allocateFrom("Привіт, Panama!");
        long length = (long) strlenHandle.invokeExact(text);
    }
}

Це вже не JNI: немає native-методу, окремого JNI glue-коду, JNIEnv* і ручного маркування кожного Java-об’єкта. Але FFM API не скасовує головного правила native interop: Java має точно знати Application Binary Interface (ABI) функції, яку викликає. Для одного strlen це легко. Для кількох сотень функцій, C-структур, enum, callback-ів та platform-залежних size_t писати FunctionDescriptor ручками — вже не дуже й ефективно. Тут і з’являється jextract.

jextract: автоматичний перекладач C ABI у Java

Як я вже писав у минулій статті, jextract читає C header-файл, пропускає його через Clang (llvm) і генерує Java-обгортки, які всередині використовують FFM API для всього, що можна експортувати з header-файлу. Цей інструмент може побудувати memory layouts для C-структури, відображення для scalar types і downcall handles для функцій. Найважливіше слово тут — C. jextract не є C++ binding generator і на те є вагомі причини та перепони. Припустимо, ми маємо такий header:

// math_api.h
#include <stdint.h>

int32_t sum_i32(int32_t left, int32_t right);

Тоді команда виглядає приблизно так:

jextract \
  --target-package dev.silo.math \
  --output src/generated/java \
  --library :/absolute/path/libmath_api.dylib \
  math_api.h

Після цього Java-код не мусить додатково описувати адресу функції, її дескриптор або int32_t. Згенерований клас уже містить потрібні MemoryLayout і MethodHandle. Це не означає, що jextract перетворює C API на ідеальний Java SDK для C-коду. Результат генерації я б розглядав як raw bindings — такі собі близькі до ABI, проте потребуючий доопрацювання код (приклад). Над ними зазвичай потрібен шар оркестрації нативною пам’яттю, додавання AutoCloseable для MethodHandle, нормальний обробник помилок, перевірка return value та зручні Java-типи (при переході від згенерованого коду до звичних і зручних класів та record-ів). Але саме прошарок C header --> Java FFM jextract робить чудово, занадто якісно!

І тут постають питання: а що із C++? Чому jextract лається на вміст hpp-файлів? І чому Java-код генерується лише для extern "C"?

Що не так із підтримкою C++

Точніше буде сказати так: FFM уміє викликати функцію за відомим ABI, але ані FFM, ані jextract не надають загального, переносного контракту для C++ ABI. На перший погляд, C++ header дуже схожий на C header-файл:

namespace geometry {
class Point {
    public:
        Point(double x, double y);
        double distance(const Point& other) const;
    };
}

Clang чудово розуміє цей код. Проблема не в тому, щоб розпарсити синтаксис, а в тому, щоб безпечно і стабільно викликати скомпільований бінарний код з іншого середовища виконання (JVM, у даному контексті). Із C ситуація значно простіша: є широко підтримувані платформозалежні ABI для scalar types, pointers, C struct та functions. У C++ поверх цього з’являються деталі, для яких немає єдиного стандартного бінарного контракту і ось чому:

• спотворення імен (mangling) і перевантаження функцій;

int sum(int left, int right);
double sum(double left, double right); 

• layout класу та memory paddings — фактичне розташування полів об’єкта в пам’яті. Для простої C-структури воно зазвичай очевидне, а для C++ класу компілятор може додати приховані сегменти даних та змінити розташування через успадкування.

struct Example {
    char flag;   // 1 байт
    int value;   // часто почнеться з offset 4, а не 1
}; 

• virtual table — якщо клас має хоча б один віртуальний метод, то об’єкт часто містить прихований покажчик на vtable (vptr), зазвичай на початку; стандарт C++ не гарантує точне місце чи навіть конкретне представлення.

class Shape {
    public:
        virtual double area() const = 0;
        virtual ~Shape() = default;
};

• множинне наслідування. У цьому випадку Report* не обов’язково має ту саму адресу, що й Serializable*. Для переходу до другого базового класу C++ може змістити покажчик на кілька байтів. Це особливо складно для віртуального наслідування.

class Printable { /* ... */ };
class Serializable { /* ... */ };

class Report : public Printable, public Serializable { /* ... */ }; 

• правила передачі/повернення класів за значенням. Для умовних Point make_point() або void process(Image image) компілятор сам вирішує, чи передавати дані через регістри, стек або прихований покажчик на пам’ять для return value. Це залежить від розміру класу, ABI, конструктора копіювання/переміщення та платформи. Java не може надійно вгадати цей calling convention.
• exceptions і stack unwinding. Коли C++ код кидає помилку, рантайм шукає відповідний catch і «розмотує» stack, викликаючи деструктори локальних об’єктів. Це потребує сумісних compiler runtime (частина стандартного середовища C++, яка реалізує винятки, RTTI, виклики деструкторів тощо) та exception metadata (службова інформація в скомпільованому коді, яка описує, як «розмотати» стек для конкретної функції). Ні в якому випадку exception не повинен перетинати C ABI або FFM downcall, розв’язання проблеми повинне відбуватися на тому ж рівні, що й місце виникнення помилки.
• std::string, std::vector, smart pointers та інші STL-типи. Це C++ класи з прихованим layout, власними правилами ownership і залежністю від реалізації стандартної бібліотеки темплейтів. Наприклад, std::string може використовувати small-string optimization, а std::vector містить специфічні для реалізації покажчики. У той же час std::unique_ptr має transfer-of-ownership семантику. Усіх їх не можна змоделювати у Java за допомогою MemoryLayout або C-структур «на око».
• templates: один template — це не одна функція, а потенційно багато спеціалізованих аспектів імплементації (ті ж C++ вектори, std::vector<typename T>, то й реалізація буде типовою).
• відмінності між компіляторами, версіями стандартної бібліотеки темплейтів, цільовими платформами та флагами, вказаними при збірці.

Навіть якщо два компілятори нібито використовують один ABI, дрібниці мають значення: libc++ чи libstdc++, debug iterator mode, exception flags, ABI макроси, архітектура, версія бібліотеки темплейтів. Отже, я сподіваюся, вже зрозуміло, що std::vector<int> не є C-структурою і не може бути нею представлений лише тому, що ми можемо подивитися на його поля через дебаг-процес.

Окремо варто розвіяти популярне непорозуміння:

extern "C" void process(std::vector<int>& values);

Навіть за наявності конструкції extern "C" аргумент такої функції все ще має тип std::vector<int>&. Його layout, життєвий цикл і семантика лишаються C++ специфічними. На жаль, така декларація не стає C API й не стає коректним входом для jextract.

Отже, повертаючись до теми, правильно ставити питання не «коли Panama підтримає C++?», а «який стабільний ABI я готовий підтримувати між Java і конкретною C++ бібліотекою?». І для більшості застосунків відповідь одна — маленький C ABI, реалізований C++ кодом.

Перехідний адаптер C++ у C: не обхід, а межа відповідальності

Перехідний адаптер від C++ до C на основі opaque handles концептуально є таким собі підходом, який, з одного боку, компілюється як C++, включає оригінальні .hpp-файли та викликає C++ API звичайним способом. З іншого — експортує зрозумілі extern "C" функції, які можна використати в jextract, а також через Linker зможе використати в Java-застосунках. Такий адаптер гарантовано не призведе до спотворення типів C++, а лише впровадить «щось» посередині між двома прямо-несумісними системами. Схема має такий вигляд:

Java application
       │
       │ FFM API / generated jextract bindings
       ▼
C header: scalars, buffers, C POD, opaque handles
       │
       ▼
C++ adapter (.cpp): ownership, conversions, exception boundary
       │
       ▼
Original C++ library: classes, templates, STL, exceptions

Це важлива архітектурна межа. Java не повинна знати layout типів C++ (системних і користувацьких). Натомість C++ адаптер сам знає, як правильно створити об’єкт, викликати його метод, зловити exception і повернути результат у формі, яку можуть зрозуміти C та Java. Для C++ об’єкта C header зазвичай декларує лише opaque handle та операції над ним:

typedef struct engine_session_handle engine_session_handle;
typedef int32_t engine_status;

engine_status engine_session_create(int32_t threads,
                                    engine_session_handle **out_session);
engine_status engine_session_process(engine_session_handle *session,
                                     const uint8_t *input,
                                     size_t input_size,
                                     int32_t *out_result);
void engine_session_release(engine_session_handle *session);

Наприклад, умовний об’єкт engine::Session, його керування пам’яттю через std::unique_ptr і обробка винятків лишаються всередині C++ реалізації. C і Java бачать лише сам покажчик, а не тип за ним. Вони можуть передати його назад у той самий адаптер та викликати release на C++ об’єкті, але не можуть самостійно створити цей об’єкт, подивитися на його поля чи трактувати його як C-структуру.

У програмуванні такий покажчик називають opaque handle (або pointer), через нього можна отримати (через відповідний набір методів-інструкцій) доступ до операцій над об’єктом, але внутрішня будова прихована задля відкритого доступу через C ABI (extern "C"). Фактично, перетворюючи складний за будовою об’єкт в поле структури, тип якого є, формально, покажчиком і вдало експортується у зовнішнє середовище. Для встановлення повноцінного доконаного контракту між Java та C++ ще треба чітко визначити, чи може значення покажчика бути null, хто відповідає за його звільнення (release) та чи дозволено використовувати об’єкт із кількох потоків (thread-safety).

Якою може бути базова технологія такого адаптера

Якщо такий адаптер C++ у C потрібен не для однієї функції, а для десятків однотипних класів і методів, у ньому починає повторюватися не бізнес-логіка, а механіка доступу. Саме повторюваність механіки доступу й можна автоматизувати у код-генерації. Не просто «згенерувати C++ binding», а послідовно побудувати C ABI адаптер з обмеженої, перевіреної підмножини C++ API. Концептуально послідовність має такий вигляд:

C++ header + compile_commands.json
              │
              ▼
Clang AST: фактичні C++ типи та overload-и
              │
              ▼
правила lowering: scalar / handle / out parameter / status
              │
              ├── C header для jextract
              ├── C++ shim, що викликає original API
              └── звіт: що згенеровано, а що свідомо відхилено

Ключовим тут є реальний build context (набір команд, флагів, header-файлів і зовнішніх бібліотек). Header-файл сам по собі не підказує Clang, з яким стандартом C++, include-ми, макросами, цільовим ABI та стандартною бібліотекою його треба читати. А отже, генератор C-коду не повинен реконструювати ці умови за здогадкою. Візьмімо максимально простий приклад:

// counter.hpp
#include <cstdint>

namespace demo {
  class Counter {
    public:
        explicit Counter(std::int32_t initial);
        std::int32_t add(std::int32_t delta);
        std::int32_t value() const;
  };
}

Для такого класу правила «пониження» (перехід від C++ до C) доволі очевидні:

• C++ клас Counter стає opaque handle;
• конструктором стає метод create з параметром out;
• функції, які будуть репрезентувати методи об’єкта класу, отримують handle (покажчик) першим аргументом;
• C++ return value переходить в out-параметр, а сама функція повертає status;
• деструктор не експортується напряму — натомість створюється release;
• C++ помилки відстежуються всередині згенерованого коду (C++ у C) і перетворюються на інтерпретовані статуси помилок (за прикладом Golang).

Враховуючи все описане вище, потенційний C header-файл може виглядати так:

// counter_capi.h - придатний для jextract
#include <stdint.h>

typedef struct demo_counter_handle demo_counter_handle;
typedef int32_t demo_status;

demo_status demo_counter_create(int32_t initial,
                                demo_counter_handle **out_handle);
demo_status demo_counter_add(demo_counter_handle *self,
                             int32_t delta,
                             int32_t *out_value);
demo_status demo_counter_value(const demo_counter_handle *self,
                               int32_t *out_value);
void demo_counter_release(demo_counter_handle *self);

Йому відповідає C++ реалізація, яка має право працювати із C++ класом:

// counter_capi.cpp - компілюється як C++ і лінкується з бібліотекою
#include "counter.hpp"
#include "counter_capi.h"

struct demo_counter_handle {
    explicit demo_counter_handle(int32_t initial) : value(initial) {}
    demo::Counter value;
};

extern "C" demo_status demo_counter_create(
        int32_t initial, demo_counter_handle **out_handle) {
    if (out_handle == nullptr) return 1;
    try {
        *out_handle = new demo_counter_handle(initial);
        return 0;
    } catch (...) {
        return 2;
    }
}

extern "C" demo_status demo_counter_add(
        demo_counter_handle *self, int32_t delta, int32_t *out_value) {
    if (self == nullptr || out_value == nullptr) return 1;
    try {
        *out_value = self->value.add(delta);
        return 0;
    } catch (...) {
        return 2;
    }
}

extern "C" demo_status demo_counter_value(
        const demo_counter_handle *self, int32_t *out_value) {
    if (self == nullptr || out_value == nullptr) return 1;
    try {
        *out_value = self->value.value();
        return 0;
    } catch (...) {
        return 2;
    }
}

extern "C" void demo_counter_release(demo_counter_handle *self) {
    delete self;
}

Як бачите, тут нема спроби прочитати C++ об’єкт із Java. Вищезгаданий C-код лише описує повторювану трансформацію:

• demo::Counter існує лише на рівні C++ коду;
• C ABI бачить opaque handle, прості числові типи з гарантованим розміром у бітах (int32_t і так далі), out-параметр і статус-код.
• jextract отримує тільки counter_capi.h — не counter.hpp.

Зачекайте, але ж існує reinterpret_cast та void*!

Все вірно, reinterpret_cast часто з’являється в обговореннях C/C++ native interop, тому варто відділити два дуже різні випадки.

Поганий випадок...

...використати reinterpret_cast, щоби переконати компілятор, ніби C++ object має C layout:

// НІ: це не робить std::vector C-структурою.
auto *fake = reinterpret_cast<my_c_vector *>(&cpp_vector);

Це не дає C-коду права читати std::vector як { pointer, size, capacity }. Такий layout не є API: він суто залежить від реалізації стандартної бібліотеки шаблонів, build-налаштувань та версії toolchain (CMake). Те саме стосується C++ класів, vtable, наслідування й std::string.

Нормальний, спеціалізований випадок...

...передати елементи вже наявного std::vector<T> у C API, який очікує буфер байтів. Тут ми не cast-имо об’єкт vector. Ми беремо data(), тобто pointer на елементи, і на час одного виклику представляємо його як pointer на байти. Розглянемо C++ template-вектор із пікселями:

template <typename Pixel>
using Image = std::vector<Pixel>;

template <typename Pixel>
void apply_filter(Image<Pixel>& image) {
    // C API обробляє лише raw bytes і повертає status.
    int rc = c_filter_apply(
            reinterpret_cast<unsigned char *>(image.data()),
            image.size() * sizeof(Pixel));

    if (rc != 0) {
        throw std::runtime_error("c_filter_apply failed");
    }
}

Тут reinterpret_cast<unsigned char*> доречний за конкретних умов:

1. image.data() вказує на безперервний масив Pixel, що гарантує std::vector;
2. C-функція справді працює з байтовим представленням, а не очікує інший тип елементів;
3. кількість байтів передається як image.size() * sizeof(Pixel);
4. покажчик не зберігається C-кодом після завершення виклику;
5. Pixel придатний для такого byte-level протоколу — наприклад, uint8_t, або інший тип із явно визначеним форматом.

Для std::vector<uint8_t> cast взагалі майже косметичний: data() вже має потрібний тип. Для std::vector<float> так само cast означає, що саме «ця C-функція бачить послідовність байтів float-масиву», а не «вона тепер може трактувати байти як будь-який інший C++ тип». Якщо C API очікує конкретно float*, краще не використовувати reinterpret_cast:

void normalize(std::vector<float>& samples) {
    c_normalize_f32(samples.data(), samples.size());
}

А якщо на межі interop потрібен об’єкт із фіксованим форматом, цей формат слід описати C POD-типом (проста C-структура без методів, успадкування, віртуальних функцій і прихованого керування пам’яттю, а декларацію можна явно описати в header-файлі) і окремо перевірити layout.

Треба обирати щось одне

reinterpret_cast — не allocator, не serializer і не засіб зробити C++ ABI «сумісним із C». Хоч reinterpret_cast і дає змогу приховати тип об’єкта C++, проте такий підхід не прибирає необхідність чітко розуміти, для якого саме типу template-а ми збираємося зробити «dereferencing». Тому й подібний підхід може працювати лише за умов чіткого розуміння, які типи й де будуть застосовуватися. Це означає, що у reinterpret_cast немає жодних переваг перед створенням такого собі opaque handle, який так само буде містити конкретні реалізації конкретних «проблемних типів C++».

Як не крути, але доводиться приймати складні рішення. C++ значно складніший за C, тому й з ним важче працювати з Java рантайму. Але навіть до початку інтеграції C++ коду в Java застосунок, розробник повинен визначитися, як саме буде інтегрований C++ код:

• opaque handle
• reinterpret_cast

Або третій варіант — множити й так нескінченну кількість С++ коду і «якось» його переводити в С. Тим самим логіка, розробка і дебаг коду стають значно дорожчими і складнішими для native interop. І, як на мене, кращою опцією є саме opaque handles, бо створення такого коду можна автоматизувати повністю, а бізнес-логіка залишиться на стороні Java застосунку.

Підведемо трохи підсумків.

Project Panama поки що не робить C++ магічно простим для Java. Він дає сучасний і стандартний у Java спосіб викликати добре описаний native ABI та працювати з native memory. Хоч jextract прибирає механічну частину роботи в моделюванні роботи С-коду Java-кодом, але його природний input — C header-файл.

І це не обмеження, яке варто ламати reinterpret_cast-ами. C++ має templates, classes, STL, exceptions і compiler-specific ABI — уся ця зручність зникає при дереференсі. Тому й найпростіший шлях інтеграції Java та C++ — прошарок у вигляді C API: scalars, явно розмірені buffers, C POD і opaque handles.

reinterpret_cast може бути корисним локальним інструментом, проте він не має перетворювати C++ object на C struct, не має приховувати ownership і не має бути контрактом між Java та STL.

Яким би не було рішення для інтеграції С++ в Java, ми вже бачимо властивості потрібного рішення: воно не повинно вдавати, що Java розуміє layout std::vector, не має пропускати C++ exception через C ABI, мусить явно фіксувати ownership, lifetime, shape буферів і версію build-контексту. Перехід від С++ в С через opaque handles — один із базових патернів, який дозволяє сформувати таку межу переходу відповідальності вручну.

Але реалізація підтримки десятків-тисяч С++ бібліотек неодмінно призведе до повторюваного boilerplate: opaque handles, create/release, status code, out parameters, exception translation, перевірки null і довжини буферів. Для однієї-двох функцій, або навіть однієї бібліотеки, це нормальна інженерна робота. Для великої C++ бібліотеки (як OpenCV або Tensor) виникає наступне, вже значно цікавіше питання: як автоматизувати цю механіку, не почавши вгадувати C++ ABI та семантику, яких у header просто немає? Про це ми й поговоримо в одній з наступних статей.

Джерела

• JEP 454: Foreign Function & Memory API
• Foreign Function and Memory API, Java SE documentation
• Jextract — the Native Library Binding Extraction Tool
• Generate Java Bindings with Jextract

Стежте за новинами та оновленнями за посиланнями:

• Dev.java — спеціальний портал Oracle для поглиблення ваших знань з Java та участі у спільноті.
• Inside.java — суто технічний блог, який ведуть архітектори та інженери, що розроблюють Java.
• Inside.java Podcast — подкаст про JDK, JVM, GC, core-libs і так далі.
• Inside.java Newscasts — щотижневе ютуб-шоу винятково про Java.
• Java on YouTube — усе про Java та екосистему.
• OpenJDK mailing lists — місце, де можна дізнатися поточний стан речей у спільноті OpenJDK.