C標準ライブラリの関数strlenについて考えます:

size_t strlen(const char *s);

これは1つの引数(文字列)を取り、その文字列の長さを返します。Javaアプリケーションからこの関数を呼び出すには、次のステップに従います:

1. strlen関数の引数のために、オフヒープ・メモリー (Javaランタイム外部のメモリー)を割り当てます。オフヒープ・メモリーの割当てを参照してください。
2. Java文字列を、割り当てたオフヒープ・メモリーに格納します。オフヒープ・メモリーの間接参照を参照してください。

   ノート:

   メソッドによっては、これらの2つのステップを1つのメソッド・コールで実行できます。オフヒープ・メモリーの割当てと移入を行うメソッドを参照してください。
3. strlen関数を指すメソッド・ハンドルを作成して呼び出します。C関数のリンクおよびコールを参照してください。

次の例は、外部関数およびメモリー(FFM) APIを使用してstrlenをコールしています:

    static long invokeStrlen(String s) throws Throwable {
        
        try (MemorySession session = MemorySession.openConfined()) {
            
            // 1. Allocate off-heap memory, and
            // 2. Dereference off-heap memory
            MemorySegment nativeString = session.allocateUtf8String(s);
        
            // 3. Link and call C function
        
            // 3a. Obtain an instance of the native linker
            Linker linker = Linker.nativeLinker();
        
            // 3b. Locate the address of the C function
            SymbolLookup stdLib = linker.defaultLookup();
            MemorySegment strlen_addr = stdLib.lookup("strlen").get();
        
            // 3c. Create a description of the C function signature
            FunctionDescriptor strlen_sig =
                FunctionDescriptor.of(ValueLayout.JAVA_LONG, ValueLayout.ADDRESS);
            
            // 3d. Create a downcall handle for the C function    
            MethodHandle strlen = linker.downcallHandle(strlen_addr, strlen_sig);            
            
            // 3e. Call the C function directly from Java
            return (long)strlen.invoke(nativeString);
        } 
    }

String s = ...
MemorySegment nativeString =
    MemorySegment.allocateNative(s.length()+1, MemorySession.global());

String s = ...  
try (MemorySession session = MemorySession.openConfined()) {
    MemorySegment.allocateNative(s.length()+1, session);
    // ...
} // nativeString is deallocated here

for(int i = 0; i < s.length(); i++) {
    nativeString.set(ValueLayout.JAVA_BYTE, i, (byte)s.charAt(i));
}

// Add the string terminator at the end
nativeString.set(ValueLayout.JAVA_BYTE, s.length(),(byte)0);

    static long invokeStrlen(String s) throws Throwable {
        
        try (MemorySession session = MemorySession.openConfined()) {
            
            // 1. Allocate off-heap memory, and
            // 2. Dereference off-heap memory
            MemorySegment nativeString = session.allocateUtf8String(s);
            // ...
        }
    }

            Linker linker = Linker.nativeLinker();

            Linker linker = Linker.nativeLinker();
            SymbolLookup libc = SymbolLookup.libraryLookup("libc.so.6", session);
            MemorySegment strlen_addr = libc.lookup("strlen").get();

            // 3a. Obtain an instance of the native linker
            Linker linker = Linker.nativeLinker();
        
            // 3b. Locate the address of the C function
            SymbolLookup stdLib = linker.defaultLookup();
            MemorySegment strlen_addr = stdLib.lookup("strlen").get();

            // 3c. Create a description of the C function signature
            FunctionDescriptor strlen_sig =
                FunctionDescriptor.of(ValueLayout.JAVA_LONG, ValueLayout.ADDRESS);

            // 3d. Create a downcall handle for the C function    
            MethodHandle strlen = linker.downcallHandle(strlen_addr, strlen_sig);  

            // 3e. Call the C function directly from Java
            return (long)strlen.invoke(nativeString);

アップコールは、ネイティブ・コードからJavaコードに戻すコールです。具体的には、これによってJavaコードを関数ポインタとして外部関数に渡すことができます。

配列の要素をソートする、標準Cライブラリ関数qsortについて考えてみます:

void qsort(void *base, size_t nmemb, size_t size,
           int (*compar)(const void *, const void *));

これは4つの引数を取ります:

• base: ソート対象の配列の最初の要素へのポインタ
• nbemb: 配列の要素数
• size: 配列内の各要素のサイズ(バイト)
• compar: 2つの要素を比較する関数へのポインタ

次の例では、qsort関数をコールしてint配列をソートします。ただし、このメソッドには2つの配列要素を比較する関数へのポインタが必要です。この例では、比較メソッド(Qsort::qsortCompare)を定義し、この比較メソッドを表すメソッド・ハンドルを作成し、このメソッド・ハンドルの関数ポインタを作成します。

    class Qsort {
        static int qsortCompare(MemoryAddress addr1, MemoryAddress addr2) {
            return Integer.compare(
                addr1.get(ValueLayout.JAVA_INT, 0),
                addr2.get(ValueLayout.JAVA_INT, 0));
        }
    }
    
    static int[] qsortTest (int[] unsortedArray) throws Throwable {
        
        int[] sortedArray;
    
        try (MemorySession session = MemorySession.openConfined()) {
            
            // Allocate off-heap memory and store unsortedArray in it
            MemorySegment array = session.allocateArray(
                ValueLayout.JAVA_INT,
                unsortedArray);            
            
            // Obtain instance of native linker
            Linker linker = Linker.nativeLinker();
            
            // Create downcall handle for qsort
            MethodHandle qsort = linker.downcallHandle(
                linker.defaultLookup().lookup("qsort").get(),
                FunctionDescriptor.ofVoid(
                    ValueLayout.ADDRESS,
                    ValueLayout.JAVA_LONG,
                    ValueLayout.JAVA_LONG,
                    ValueLayout.ADDRESS)
            );  
            
            // Create method handle for qsortCompare
            FunctionDescriptor compareFunc_sig = FunctionDescriptor.of(
                ValueLayout.JAVA_INT,
                ValueLayout.ADDRESS,
                ValueLayout.ADDRESS);

            MethodHandle comparHandle = MethodHandles.lookup().findStatic(
                Qsort.class, "qsortCompare", Linker.upcallType(compareFunc_sig));

            // Create function pointer for qsortCompare                    
            MemorySegment comparFunc = linker.upcallStub(comparHandle,
                compareFunc_sig, session);            
           
            // Call qsort
            qsort.invoke(array, (long) unsortedArray.length, 4L, comparFunc);

            // Dereference off-heap memory
            sortedArray = array.toArray(ValueLayout.JAVA_INT);
        }
        return sortedArray;    
    }

次の文によって、オフヒープ・メモリーが割り当てられ、ソート対象のint配列が格納されます:

            // Allocate off-heap memory and store unsortedArray in it
            MemorySegment array = session.allocateArray(
                ValueLayout.JAVA_INT,
                unsortedArray);  

次の文によって、qsort関数のダウンコール・メソッド・ハンドルが作成されます:

            // Obtain instance of native linker
            Linker linker = Linker.nativeLinker();
            
            // Create downcall handle for qsort
            MethodHandle qsort = linker.downcallHandle(
                linker.defaultLookup().lookup("qsort").get(),
                FunctionDescriptor.ofVoid(
                    ValueLayout.ADDRESS,
                    ValueLayout.JAVA_LONG,
                    ValueLayout.JAVA_LONG,
                    ValueLayout.ADDRESS)
            ); 

次のクラスによって、2つの要素(この場合は2つのint値)を比較するJavaメソッドが定義されます:

    class Qsort {
        static int qsortCompare(MemoryAddress addr1, MemoryAddress addr2) {
            return Integer.compare(
                addr1.get(ValueLayout.JAVA_INT, 0),
                addr2.get(ValueLayout.JAVA_INT, 0));
        }
    }

このメソッドでは、int値はMemoryAddressオブジェクトによって表されます。メモリー・アドレスによって、メモリーの場所への参照がモデル化されます。メモリー・アドレスの値を取得するには、そのgetメソッドの1つをコールします。この例では、get(ValueLayout.OfInt, long)をコールします。ここで、2番目の引数は、メモリー・アドレスの場所を基準としたオフセット(バイト単位)です。この例のメモリー・アドレスには1つの値しか格納されないため、2番目の引数は0です。

次の文によって、比較メソッドQsort::qsortCompareを表すメソッド・ハンドルが作成されます:

            // Create method handle for qsortCompare
            FunctionDescriptor compareFunc_sig = FunctionDescriptor.of(
                ValueLayout.JAVA_INT,
                ValueLayout.ADDRESS,
                ValueLayout.ADDRESS);

            MethodHandle comparHandle = MethodHandles.lookup().findStatic(
                Qsort.class, "qsortCompare", Linker.upcallType(compareFunc_sig));

MethodHandles.Lookup::findStaticメソッドは、静的メソッドのメソッド・ハンドルを作成します。これは次の3つの引数を取ります。

• メソッドのクラス
• メソッドの名前
• メソッドの型: MethodType::methodTypeの最初の引数は、メソッドの戻り値の型です。残りは、メソッドの引数の型です。

次の文によって、メソッド・ハンドルcomparHandleの関数ポインタが作成されます:

            // Create function pointer for qsortCompare                    
            MemorySegment comparFunc = linker.upcallStub(comparHandle,
                compareFunc_sig, session);    

Linker::upcallStubメソッドは3つの引数を取ります:

• 関数ポインタを作成するメソッド・ハンドル
• 関数ポインタの関数ディスクリプタ。この例では、FunctionDescriptor.ofの引数はQsort::qsortCompareの戻り値の型と引数に対応しています
• 関数ポインタ(メモリー・セグメント)に関連付けるメモリー・セッション

次の文によって、qsort関数がコールされます:

            // Call qsort
            qsort.invoke(array, (long) unsortedArray.length, 4L, comparFunc);

この例で、MethodHandle::invokeの引数は、標準Cライブラリqsort関数の引数に対応します。

最後に、次の文によって、ソートされた配列値がオフヒープ・メモリーからオンヒープ・メモリーにコピーされます:

            // Dereference off-heap memory
            sortedArray = array.toArray(ValueLayout.JAVA_INT);

基本的な間接参照操作のみを使用して構造化データにアクセスすると、保守が困難で理解しにくいコードになる可能性があります。かわりに、メモリー・レイアウトを使用すると、より複雑なネイティブ・データ型(C構造体など)を効率よく初期化してアクセスすることができます。

たとえば、次のC宣言について考えてみます。これはPoint構造体の配列を定義し、各Point構造体にはPoint.xとPoint.yという2つのメンバーが含まれます:

struct Point {
   int x;
   int y;
} pts[10];

このようなネイティブ配列は、次のように初期化できます:

        try (MemorySession session = MemorySession.openConfined()) {

            MemorySegment segment =
                MemorySegment.allocateNative(2 * 4 * 10, session);

            for (int i = 0; i < 10; i++) {
                segment.setAtIndex(ValueLayout.JAVA_INT, (i * 2),     i); // x
                segment.setAtIndex(ValueLayout.JAVA_INT, (i * 2) + 1, i); // y
            }
            // ...
        }

MemorySegment::allocateNativeメソッドは、この配列に必要なバイト数を計算します。MemorySegment::setAtIndexメソッドは、Point構造体の各メンバーに書き込むためのメモリー・アドレスのオフセットを計算します。これらの計算を回避するには、メモリー・レイアウトを使用できます。

Point構造体の配列を表すために、次の例ではシーケンス・メモリー・レイアウトを使用します:

        try (MemorySession session = MemorySession.openConfined()) {
            
            SequenceLayout ptsLayout
                = MemoryLayout.sequenceLayout(10,
                    MemoryLayout.structLayout(
                        ValueLayout.JAVA_INT.withName("x"),
                        ValueLayout.JAVA_INT.withName("y")));

            VarHandle xHandle
                = ptsLayout.varHandle(PathElement.sequenceElement(),
                    PathElement.groupElement("x"));
            VarHandle yHandle
                = ptsLayout.varHandle(PathElement.sequenceElement(),
                    PathElement.groupElement("y"));            

            MemorySegment segment =
                MemorySegment.allocateNative(ptsLayout, session);
            
            for (int i = 0; i < ptsLayout.elementCount(); i++) {
                xHandle.set(segment, (long) i, i);
                yHandle.set(segment, (long) i, i);
            }
            // ...
        }

最初の文によって、SequenceLayoutオブジェクトで表されるシーケンス・メモリー・レイアウトが作成されます。これには、GroupLayoutオブジェクトで表される10個の構造体レイアウトのシーケンスが含まれます。メソッドMemoryLayout::structLayoutは、GroupLayoutオブジェクトを返します。各構造体レイアウトには、xとyという名前の2つのJAVA_INT値レイアウトが含まれます:

            SequenceLayout ptsLayout
                = MemoryLayout.sequenceLayout(10,
                    MemoryLayout.structLayout(
                        ValueLayout.JAVA_INT.withName("x"),
                        ValueLayout.JAVA_INT.withName("y")));

事前定義値ValueLayout.JAVA_INTには、Java int値に必要なバイト数に関する情報が含まれます。

次の文によって、メモリー・アドレス・オフセットを取得する2つのメモリー・アクセスVarHandleが作成されます。VarHandleは、動的な強い型指定の参照であり、変数を参照するか、パラメータによって定義された変数ファミリ(静的フィールド、非静的フィールド、配列要素、オフヒープデータ構造体のコンポーネント)を参照します。

            VarHandle xHandle
                = ptsLayout.varHandle(PathElement.sequenceElement(),
                    PathElement.groupElement("x"));
            VarHandle yHandle
                = ptsLayout.varHandle(PathElement.sequenceElement(),
                    PathElement.groupElement("y")); 

メソッドPathElement.sequenceElement()は、シーケンス・レイアウトからメモリー・レイアウトを取得します。この例では、構造体レイアウトの1つをptsLayoutから取得します。メソッド・コールPathElement.groupElement("x")は、xという名前のメモリー・レイアウトを取得します。名前が付いたメモリー・レイアウトを作成するにはwithName(String)メソッドを使用します。

for文によって、VarHandle::setがコールされ、MemorySegment::setAtIndexのようにメモリーを間接参照します。この例では、値(2番目の引数)がメモリー・セグメント(最初の引数)のインデックス(3番目の引数)に設定されます。VarHandle xHandleおよびyHandleは、Point構造体のサイズ(8バイト)とそのintメンバーのサイズ(4バイト)を認識しています。つまり、setAtIndexメソッドのように、配列の要素またはメモリー・アドレス・オフセットに必要なバイト数を計算する必要はありません。

            MemorySegment segment =
                MemorySegment.allocateNative(ptsLayout, session);
            
            for (int i = 0; i < ptsLayout.elementCount(); i++) {
                xHandle.set(segment, (long) i, i);
                yHandle.set(segment, (long) i, i);
            }

外部関数およびメモリー(FFM) APIの一部のメソッドは安全ではないため、制限されます。制限されたメソッドは、正しく使用しないと、JVMをクラッシュさせ、メモリーの破損につながる可能性があります(エラーは表示されません)。

実行するアプリケーションで、次に示す制限されたメソッドのいずれかが呼び出されると、Javaランタイムによって警告メッセージが出力されます:このメッセージを抑制するには、--enable-native-access=ALL-UNNAMEDコマンドライン・オプションを追加します。

• static Linker nativeLinker()、SymbolLookup.libraryLookup(String, MemorySession)およびSymbolLookup.libraryLookup(Path, MemorySession): これらのメソッドはダウンコール・メソッド・ハンドルを作成するために必要ですが、これは本質的に安全ではありません。通常、外部ライブラリのシンボルには、十分なシグネチャ情報(外部関数パラメータの個数や型など)が含まれていないため、リンカーが実行時にリンク要求を検証できません。クライアントがやり取りするダウンコール・メソッド・ハンドルが、無効なリンク要求によって取得されていたとき(たとえば、指定した関数ディスクリプタの引数レイアウトが多すぎた場合など)、このようなやり取りの結果は未指定となり、JVMがクラッシュする可能性があります。

  JVMはアップコールでクラッシュする可能性があります。アップコールは、通常、ダウンコール・メソッド・ハンドル呼出しのコンテキストで呼び出されるためです。

• MemoryAddressのすべての間接参照メソッド: メモリー・アドレスには時間的または空間的な境界がないため、ランタイムにはメモリー間接参照操作の正確性をチェックする方法がありません。
• MemorySegment::ofAddressおよびVaList::ofAddress: 場合によっては、ネイティブ・コードから取得したメモリー・アドレスを、完全な空間境界、時間境界および限定境界のすべてを備えたメモリー・セグメントに変換する必要があります。このために、クライアントはセグメント・サイズとセグメント・セッションを指定して、メモリー・アドレスからネイティブ・セグメントを取得できますが、安全ではありません。これは制限された操作です。たとえば、セグメント・サイズが正しくない場合、メモリー・セグメントを間接参照しようとしてJVMがクラッシュする可能性があるためです。

jextractツールは、ネイティブ・ライブラリのヘッダー・ファイルからJavaバインディングを機械的に生成します。このツールが生成するバインディングは、外部関数およびメモリー(FFM) APIに依存します。このツールを使用すると、呼び出す関数のダウンコール・ハンドルおよびアップコール・ハンドルを作成する必要はありません。jextractツールによって、そのためのコードが生成されます。

jextractのソース・コードは次のサイトで入手します:

https://github.com/openjdk/jextract

このサイトには、jextractをコンパイルおよび実行する方法のステップ、その他のドキュメントおよびサンプルも含まれています。