• ホーム
• 最新
• リファレンスマニュアル
• ネイティブイメージ
• ネイティブコードの相互運用性

ネイティブイメージにおける外部関数およびメモリアプリケーションプログラミングインターフェース (API)

外部関数およびメモリ (FFM) API は、Java コードがネイティブコードと対話し、その逆も可能にするインターフェースです。JDK 22 で JEP 454 で最終決定されました。ネイティブイメージでのサポートは現在実験段階であり、-H:+ForeignAPISupport (に加えて -H:+UnlockExperimentalVMOptions) で明示的に有効にする必要があります。「制限付き」のネイティブ操作 (ネイティブコードとの間での呼び出しのハンドル作成など) を実行できるモジュールは、--enable-native-access= オプションを使用して指定する必要があります。このページでは、ネイティブイメージでの FFM API のサポートの概要を説明します。

外部メモリ #

外部メモリ機能は一般的にサポートされています。共有アリーナは現在サポートされていません。

外部関数 #

FFM API を使用すると、Java コードからネイティブ関数をダウン呼び出しでき、逆にネイティブコードからアップ呼び出してメソッドハンドル経由で Java コードを呼び出すことができます。これらの 2 種類の呼び出しは、それぞれ「ダウンコール」と「アップコール」と呼ばれ、まとめて「外部呼び出し」と呼ばれます。

注: 現在、外部呼び出しは x64 アーキテクチャでサポートされています。具体的には、ダウンコールは x64 Linux、Windows、macOS でサポートされていますが、アップコールは x64 Linux のみでサポートされています。

ネイティブ関数の検索 #

FFM API は、名前でネイティブライブラリ内の関数を検索するための SymbolLookup インターフェースを提供します。現在、SymbolLookup.loaderLookup() が唯一サポートされている種類の SymbolLookup です。

外部呼び出しの登録 #

実行時にネイティブコードへの呼び出しを実行するには、イメージビルド時にサポートコードを生成する必要があります。したがって、native-image ツールには、実行時にダウンコールを実行できる関数を特徴付ける記述子を提供する必要があります。

これらの記述子は、カスタム Feature を使用して登録できます。例:

import static java.lang.foreign.ValueLayout.*;

class ForeignRegistrationFeature implements Feature { 
  public void duringSetup(DuringSetupAccess access) {
    RuntimeForeignAccess.registerForDowncall(FunctionDescriptor.ofVoid());
    RuntimeForeignAccess.registerForUpcall(FunctionDescriptor.ofVoid());
    RuntimeForeignAccess.registerForDowncall(FunctionDescriptor.ofVoid(), Linker.Option.critical(false));
    RuntimeForeignAccess.registerForUpcall(FunctionDescriptor.of(JAVA_INT, JAVA_INT));
    RuntimeForeignAccess.registerForUpcall(FunctionDescriptor.of(JAVA_INT, JAVA_INT, JAVA_INT));
    RuntimeForeignAccess.registerForDowncall(FunctionDescriptor.of(ADDRESS, JAVA_INT, JAVA_INT), Linker.Option.firstVariadicArg(1));
    RuntimeForeignAccess.registerForDowncall(FunctionDescriptor.ofVoid(JAVA_INT), Linker.Option.captureCallState("errno"));
  }
}

カスタム機能をアクティブ化するには、--features=com.example.ForeignRegistrationFeature オプション (機能クラスの完全修飾名) を native-image に渡します。native-image.properties ファイルを使用することをお勧めします。

関連ドキュメント #

• ネイティブコードとの相互運用性