تقدير المشروع
← كل المقالات

قل مرحبًا لـ Panama

مع JEP-454، أصبحت واجهة Foreign Function & Memory (FFM) API ميزة مستقرة. بدءًا من JDK 22، يستطيع المطورون استخدام هذه الواجهة دون أي إعداد إضافي أو "عناء". تتناول هذه المقالة كيف تجعل واجهة FFM API العمل مع المكتبات الأصلية أبسط وتحسّن الأداء.

9 دقائق قراءة
JavaJVMProject Panama

مع JEP-454، أصبحت واجهة Foreign Function & Memory (FFM) API ميزة مستقرة. بدءًا من JDK 22، يستطيع المطورون استخدام هذه الواجهة دون أي إعداد إضافي أو “عناء”. تتناول هذه المقالة كيف تجعل واجهة FFM API العمل مع المكتبات الأصلية أبسط وتحسّن الأداء.

الإعداد

الكود مكتوب بـ Java، لكنني شغّلته باستخدام Scala-CLI لأنه يُبقي الأمور بسيطة. وشُغّلت اختبارات الأداء (benchmarks) على جهاز Intel(R) Xeon(R) @ 2.20GHz بمواصفات 4 vCPUs (2 cores), 16GB RAM، على نظام Debian GNU/Linux 12 (bookworm) مع OpenJDK Runtime Environment Temurin-25.0.1+8 (build 25.0.1+8-LTS).

مثال

لتوضيح هذه المزايا، سأستخدم الدالة pow من المكتبة libm.so. ولإجراء مقارنة عادلة، لنرَ أولًا كيف تُستدعى هذه الدالة عبر واجهة JNI الكلاسيكية.

JNI

يتضمن استدعاء دالة أصلية عبر واجهة JNI عددًا من الخطوات اليدوية.

في البداية، نصرّح عن دالة Java بالكلمة المفتاحية native، التي تعمل كبديل مؤقت للتنفيذ الأصلي:

public static native double calculate(double base, double exponent);

يستخدم المثال دالة static، لكن ذلك ليس ضروريًا بالمعنى الصارم. ومع ذلك، فإن كون الدالة ساكنة أو لا يؤثر في المعاملات التي تُمرَّر إلى الدالة الأصلية (المزيد عن ذلك بعد قليل).

ثم نولّد ملف ترويسة C/C++ بمصرِّف Java. ويعمل هذا الملف بمثابة “الجسر” بين Java وC:

javac -h native/ src/main/java/methods/JNIPowerCalculator.java

يخبر هذا الأمر مصرِّف Java بالبحث عن الدوال native في JNIPowerCalculator.java وكتابة ملف ترويسة في المجلد native/. وبالنسبة إلى دالتنا، يكون التصريح الناتج:

JNIEXPORT jdouble JNICALL Java_methods_JNIPowerCalculator_calculate
  (JNIEnv *, jclass, jdouble, jdouble);
  • JNIEXPORT – ماكرو يجعل الدالة مرئية لـ JVM.
  • jdouble – نوع الإرجاع كما يقابله JNI (ما يناظر double في Java).
  • JNICALL – ماكرو يضمن اصطلاح الاستدعاء الصحيح (الذي يختلف بين أنظمة التشغيل، مثل Windows مقابل Linux).
  • Java_methods_JNIPowerCalculator_calculate هو اسم الدالة، الذي يجب أن يخضع لاصطلاح تسمية صارم:

a) Java_

b) package_

c) class_

d) اسم الدالة

  • JNIEnv * – مؤشر إلى بيئة JNI، يُستخدم للتفاعل مع JVM (مثلًا لإنشاء كائنات Java أو رمي استثناءات).
  • jclass – مرجع إلى الصنف الذي يحتوي الدالة. وبالنسبة إلى دالة غير ساكنة، سيكون هذا المعامل بدلًا من ذلك jobject (مرجع إلى النسخة المعينة).
  • وأخيرًا، هناك وسيطان من النوع jdouble، وهما وسيطا الدالة.

بعد ذلك يأتي تنفيذ C الفعلي، الذي يكتفي هنا بالتفويض إلى مكتبة الرياضيات القياسية:

JNIEXPORT jdouble JNICALL Java_methods_JNIPowerCalculator_calculate
  (JNIEnv *env, jclass clazz, jdouble base, jdouble exponent) {
    return pow(base, exponent);
}

وأخيرًا، يجب تصريف كود C إلى مكتبة مشتركة يستطيع JVM تحميلها:

gcc -shared -fPIC \
 -I"$JAVA_HOME/include" \
 -I"$JAVA_HOME/include/linux" \
 native/PowerCalculator.c -o lib/libnative-power-calculator.so -lm
  • -shared – ينتج مكتبة مشتركة (.so) بدلًا من ملف تنفيذي.
  • -fPIC – ينتج Position Independent Code، الذي تحتاج إليه المكتبات المشتركة على Linux لتتمكن من التحميل عند أي عنوان في الذاكرة دون تعارضات.
  • -I – يوجّه المصرِّف إلى ملفات الترويسة المطلوبة.
  • -o – يحدد مسار المخرجات واسم الملف.
  • -lm – يربط مكتبة الرياضيات القياسية (m)، حتى يمكن استخدام الدالة pow.

من الواضح أنه حتى استدعاء دالة أصلية بسيطة يتطلب كثيرًا من كود “boilerplate” وأدوات خارجية. ولا توجد طريقة لاستدعاء الدالة الأصلية مباشرة – فعليك كتابة غلاف وتصريفه يستوفي قواعد التسمية والمعاملات الصارمة في JNI.

لنرَ الآن كيف غيّرت واجهة FFM API الأمور.

Project Panama

بفضل واجهة Foreign Function & Memory (FFM) API، يمكن استدعاء الدالة pow نفسها بالكامل من Java، دون أي كود “لاصق” بلغة C. وكل شيء يبدأ بالحصول على MethodHandle. يمكن أن يبدو مثال الكود هكذا:

public class PanamaPowerCalculator {
    private static final MethodHandle METHOD_HANDLE;

    static {
        (1) Linker linker = Linker.nativeLinker();
        Map<String, MemoryLayout> layouts = (3) linker.canonicalLayouts();
        (5) MemorySegment symbol = linker.defaultLookup().find("pow").get();
        (2) ValueLayout cDouble = (ValueLayout) layouts.get("double");
        (4) FunctionDescriptor fd = FunctionDescriptor.of(cDouble, cDouble, cDouble);
        (6) METHOD_HANDLE = linker.downcallHandle(symbol, fd);
    }
    ...
}
  1. Linker – يمنح الوصول إلى الدوال الأجنبية.
  2. ValueLayout – يصف حجم أنواع البيانات الأساسية ومحاذاتها، مثل Integer وLong، ….
  3. canonicalLayouts – يوفّر التخطيطات القياسية لأنواع بيانات C لنظام التشغيل والمعالج الأساسيين. وهذا مهم لأنها قد تختلف بين أنظمة التشغيل، مثلًا: في Windows يكون النوع long عادةً 32 بتًا، بينما يكون 64 بتًا في Linux.
  4. FunctionDescriptor – يصف توقيع الدالة الأجنبية. الوسيط الأول هو تخطيط نوع الإرجاع، والوسيطان التاليان هما تخطيطا الوسيطين.
  5. MemorySegment – يمنح الوصول إلى مناطق متجاورة من الذاكرة – هنا، إلى الدالة pow.
  6. MethodHandle – مرجع إلى دالة أجنبية يمكن تنفيذها مباشرة.

يُجري المثال أعلاه استدعاءً نازلًا (downcall) (استدعاء دالة أصلية من Java). والجدير بالذكر أن واجهة FFM API تدعم الاتجاه المعاكس أيضًا: الاستدعاءات الصاعدة (upcalls).

وباستخدام upcallStub، يمكن تمرير مقبض دالة Java إلى الكود الأصلي كمؤشر دالة، مما يتيح لكود C “الاستدعاء الراجع” إلى تطبيق Java لديك. لكن هذه المقالة تتناول حالة downcall فقط.

بعد تهيئة MethodHandle لاستدعاء نازل، يمكن تنفيذه بالدالة invoke أو invokeExact.

الدالة invoke متسامحة. فعندما لا تطابق الوسائط التي تمررها FunctionDescriptor تمامًا، يحاول JVM تحويل الأنواع تلقائيًا قبل إجراء الاستدعاء الأصلي.

public static double calculateInvokeWithConversion(int base, int exponent) {
   try {
      return (double) METHOD_HANDLE.invoke(base, exponent);
   } catch (Throwable t) {
      throw new RuntimeException(t);
   }
}

أما الدالة invokeExact فتتطلب، على العكس، أن تطابق الأنواع FunctionDescriptor بدقة. وتمرير وسيط من نوع خاطئ ينتج عنه فورًا WrongMethodTypeException.

public static double calculateInvokeExact(double base, double exponent) {
   try {
      return (double) METHOD_HANDLE.invokeExact(base, exponent);
   } catch (Throwable t) {
      throw new RuntimeException(t);
   }
}

نهج FFM أنظف وأسهل صيانةً بكثير من JNI. فهو يستغني عن ترويسات C والمصرِّفات الخارجية وكود “اللصق”، فيبقى كل المنطق داخل منظومة Java.

لكن هل يمكننا الذهاب أبعد من ذلك؟ يوضح القسم التالي كيف يمكن لـ jextract أتمتة العملية بأكملها.

Jextract

كتابة منطق MethodHandle وFunctionDescriptor يدويًا مقبولة لدالة واحدة مثل pow، لكنها تصبح مملة وعرضة للأخطاء مع المكتبات الأكبر. وهنا يتدخل jextract.

تولّد أداة jextract روابط Java تلقائيًا من ترويسات المكتبات الأصلية. والجدير بالذكر أنها، رغم أنها بدأت داخل OpenJDK، تُصان الآن كأداة مستقلة ليمكنها التطور بمعزل عن دورة إصدار JDK الرئيسية.

ستحتاج إلى الملف التنفيذي jextract لاستخدامها. يولّد هذا الأمر غلاف Java للدالة pow:

jextract --output src/main/java \
-t math \
/usr/include/math.h \
--header-class-name NativeMath \
--include-function pow
  • --output – المجلد الهدف لملفات المصدر المولَّدة.
  • -t – اسم حزمة Java الهدف.
  • /usr/include/math.h – ملف الترويسة المراد تحليله.
  • --header-class-name – اسم صنف Java الذي سيحتوي الدوال الأصلية.
  • --include-function – يضيّق ما يُولَّد. ومن دونه، كان jextract سيحاول توليد روابط لكل دالة في math.h.

وعادةً ينتج الأمر ملفين رئيسيين:

  • NativeMath.java – يعرض دوال Java عالية المستوى التي تستدعيها مباشرة، ويعمل كالواجهة الرئيسية للمكتبة الأصلية.
  • NativeMath$shared.java – يحتوي على “السباكة” خلف الكواليس، مثل تخطيطات الذاكرة، التي تخبر JVM كيف يتعامل مع أنواع البيانات الأصلية.

بعد أن غطينا JNI وPanama المكتوب يدويًا وPanama المولَّد بواسطة jextract، لنقارن كيف يؤدي كلٌّ منها ونتحقق مما إذا كان “boilerplate” يؤثر فعلًا في السرعة.

المقارنة

لقياس مدى كفاءة هذه النُّهُج، شغّلت اختبار أداء JMH يقارن بين خمسة تنفيذات:

  • JNI API: الجسر الأصلي الكلاسيكي.
  • Panama invokeExact.
  • Panama invoke (With Conversion): وسائط int تُمرَّر إلى توقيع double.
  • Panama invoke (Matching Types): وسائط double تُمرَّر مباشرة
  • jextract: الاعتماد على الروابط المولَّدة تلقائيًا.

نتائج اختبار الأداء:

Benchmark                                                                              Mode  Cnt   Score   Error  Units
NativeMethodCallBenchmark.benchmark_JNI_Power_Calculator                               avgt   15  34.659 ? 0.198  ns/op
NativeMethodCallBenchmark.benchmark_Panama_Invoke_Exact_Power_Calculator               avgt   15  29.541 ? 0.222  ns/op
NativeMethodCallBenchmark.benchmark_Panama_Invoke_With_Conversion_Power_Calculator     avgt   15  34.310 ? 0.312  ns/op
NativeMethodCallBenchmark.benchmark_Panama_Invoke_Without_Conversion_Power_Calculator  avgt   15  29.554 ? 0.138  ns/op
NativeMethodCallBenchmark.benchmark_Panama_J_Extract_Power_Calculator                  avgt   15  29.413 ? 0.067  ns/op

وفقًا للنتائج، يأتي invokeExact وinvoke (مع الأنواع المطابقة) وjextract في المقدمة، متساوية عمليًا عند حوالي 29.5 ns. أما الخيارات المتبقية فأبطأ بنحو 5ns (17%).

لكن هذه الـ 29.5 ns تشمل أيضًا الوقت المستغرق في حساب pow نفسه داخل libm.so. ولمعرفة التكلفة الحقيقية للانتقال من Java إلى الكود الأصلي، شغّلت اختبار الأداء مع المحلِّل perfasm:

scala-cli . --jmh --power -- -f 1 -prof "perfasm:events=cpu-clock;intel=true"

جعل الحمل الإضافي للمحلِّل الأرقام مختلفة قليلًا، لكن النمط العام بقي كما هو:

Benchmark                                                                                  Mode  Cnt   Score    Error  Units
NativeMethodCallBenchmark.benchmark_JNI_Power_Calculator                                   avgt    5  35.050 ?  3.193  ns/op
NativeMethodCallBenchmark.benchmark_Panama_Invoke_Exact_Power_Calculator                   avgt    5  30.336 ?  7.101  ns/op
NativeMethodCallBenchmark.benchmark_Panama_Invoke_With_Conversion_Power_Calculator         avgt    5  36.807 ? 12.709  ns/op
NativeMethodCallBenchmark.benchmark_Panama_Invoke_Without_Conversion_Power_Calculator      avgt    5  29.660 ?  0.335  ns/op
NativeMethodCallBenchmark.benchmark_Panama_J_Extract_Power_Calculator                      avgt    5  30.168 ?  6.217  ns/op

أظهرت مخرجات المحلِّل أن العملية الرياضية نفسها في libm.so تستغرق نحو 17 ns. وبطرح “زمن العمل” هذا من الإجماليات نحصل على:

  • الحمل الإضافي لـ Panama: ~12.5 ns
  • الحمل الإضافي لـ JNI/التحويل: ~17.5 ns

وبهذا المنظور، تتفوق حلول Panama الأسرع على الأبطأ بنحو 30% في الحمل الإضافي الصرف للاستدعاء.

وبطبيعة الحال، ينطبق هذا على مثال بسيط كهذا فقط. فلو كانت مكتبتنا الأصلية تؤدي أنواعًا أخرى من العمل، لكان المكسب أكبر أو أصغر قليلًا، بحسب نسبة “العمل” إلى “الحمل الإضافي للاستدعاء”. ومع ذلك، دعونا نحاول فهم لماذا بعض الحلول أسرع من غيرها.

تحليل الأداء

لتبسيط التنقيح باستخدام jhsdb، أضفت صنف Main إلى المشروع. فالكود الذي يصرّفه JIT في تطبيق عادي ليس دائمًا نفسه كود JMH المحسَّن بشدة، لكنه يعطي رؤية جيدة لكيفية تعامل JVM مع هذه الاستدعاءات.

كود التجميع (assembly) المولَّد للحلول الثلاثة الأسرع (invokeExact وinvoke – بدون تحويل، وjextract) متشابه جدًا:

0x00007fa5dfef0166:    movabs $0x7fa5f7a682b0,%rsi
...
0x00007fa5dfef0178:    movabs $0x7157a5328,%rdx
0x00007fa5dfef0182:    nop
0x00007fa5dfef0183:    call   0x00007fa5dfede980
  • يحتوي السجل rsi على عنوان ذاكرة الدالة pow.
  • يحتوي السجل rdx على عنوان NativeEntryPoint.
  • يحتفظ NativeEntryPoint بمرجع إلى nep_invoker_blob، وهو مقطع مخصص ينفّذ الانتقال إلى الدالة الأصلية بتعليمات إضافية قليلة جدًا.

مع JNI، ينتج JVM الغلاف native_wrapper. وهو، مثل nep_invoker_blob، يربط بين JVM والدالة الأجنبية، لكنه أقل تحسينًا بكثير. وفوق ذلك، يضيف غلاف C الخاص بنا طبقة إضافية من الحمل لا يستطيع JIT إزالتها بالتحسين.

أما مع invoke والتحويل بين الأنواع، فالطريق إلى الدالة الأصلية أطول بكثير. فهو ينتهي باستدعاء nep_invoker_blob، لكن مصرِّف JIT لا يستطيع تطبيق التحسينات الجريئة نفسها، لأن عليه توليد منطق يحوّل أنواع البيانات قبل أن تعبر الحدود الأصلية.

الخلاصة

تجعل واجهة Foreign Function & Memory (FFM) API التفاعل مع المكتبات الأصلية أبسط بكثير. وكما تُظهر اختبارات الأداء لدينا، فإن هذه البساطة تجلب أيضًا أداءً أفضل. ولأن مصرِّف JIT يستطيع تحسين مسار الاستدعاء مباشرة، فإن واجهة FFM API تخفّض الحمل الإضافي للاستدعاء بنحو 30% (كما هو موضح أعلاه) مقارنةً بـ JNI الكلاسيكية.

سواء اعتمدت على jextract للأتمتة أو على MethodHandle للتحكم اليدوي، فستحصل على طريقة أسرع وأكثر أمانًا وأسهل صيانةً لاستخدام الكود الأصلي في Java الحديثة.

آمل أن تجد هذه المقالة مفيدة.