オフヒープ・データは、JVMのヒープとも呼ばれるJavaランタイム外部のメモリーに格納されるデータです。オフヒープ・データはオフヒープ・メモリーに格納され、MemorySegmentオブジェクトによって表されます。ヒープ・メモリーとは異なり、オフヒープ・メモリーは不要になった際にガベージ・コレクションの対象になりません。オフヒープ・メモリーの割当ておよび割当て解除の方法とタイミングを制御できます。

JavaアプリケーションでCなど異なる言語の関数やメソッドを呼び出すには、その引数がオフヒープ・メモリー内にある必要があります。

次の例では、オフヒープ・メモリーを割り当て、Java Stringを格納してから、オフヒープ・メモリーの内容を出力します。

    static void allocateCharArray(String s) {
        try (Arena arena = Arena.openConfined()) {

            // Allocate off-heap memory
            MemorySegment nativeText = arena.allocateUtf8String(s);

            // Access off-heap memory
            for (int i = 0; i < s.length(); i++ ) {
               System.out.print((char)nativeText.get(ValueLayout.JAVA_BYTE, i)); 
            }
            
        } // Off-heap memory is deallocated                  
    }

    static void allocateCharArrayError(String s) {
        
        MemorySegment nativeText;
        try (Arena arena = Arena.openConfined()) {

            // Allocate off-heap memory
            nativeText = arena.allocateUtf8String(s);
        }
        for (int i = 0; i < s.length(); i++ ) {
            // Exception in thread "main" java.lang.IllegalStateException: Already closed
            System.out.print((char)nativeText.get(ValueLayout.JAVA_BYTE, i)); 
        } 
    }

    static void allocateCharArray(String s) {
        try (Arena arena = Arena.openConfined()) {

            // Allocate off-heap memory
            MemorySegment nativeText = arena.allocateUtf8String(s);
            // ...

            // Access off-heap memory
            for (int i = 0; i < s.length(); i++ ) {
               System.out.print((char)nativeText.get(ValueLayout.JAVA_BYTE, i)); 
            }

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

    static long invokeStrlen(String s) throws Throwable {
        
        try (Arena arena = Arena.openConfined()) {
            
            // 1. Allocate off-heap memory, and
            // 2. Dereference off-heap memory
            MemorySegment nativeString = arena.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 libc = linker.defaultLookup();
            MemorySegment strlen_addr = libc.find("strlen").get();
        
            // 3c. Create a description of the native 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.invokeExact(nativeString);
        } 
    }

strlen C標準ライブラリ関数の宣言を次に示します:

size_t strlen(const char *s);

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

1. strlen関数の引数のために、オフヒープ・メモリー (Javaランタイム外部のメモリー)を割り当てます。

2. Java文字列を、割り当てたオフヒープ・メモリーに格納します。

   invokeStrlenの例では、前のステップとこのステップを次の文で実行します:

   MemorySegment nativeString = arena.allocateUtf8String(s);

3. strlen関数を指すメソッド・ハンドルを作成して呼び出します。この項のトピックでその方法を説明します。

            Linker linker = Linker.nativeLinker();

        try (Arena arena = Arena.openConfined()) {    
            SymbolLookup libc = SymbolLookup.libraryLookup("libc.so.6", arena.scope());
            MemorySegment strlen_addr = libc.find("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.find("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.invokeExact(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)を定義し、この比較メソッドを表すメソッド・ハンドルを作成し、このメソッド・ハンドルの関数ポインタを作成します。

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

public class InvokeQsort {
        
    class Qsort {
        static int qsortCompare(MemorySegment addr1, MemorySegment addr2) {
            return addr1.get(ValueLayout.JAVA_INT, 0) - addr2.get(ValueLayout.JAVA_INT, 0);
        }
    }
    
    // Obtain instance of native linker
    final static Linker linker = Linker.nativeLinker();
    
    // Create downcall handle for qsort
    final static MethodHandle qsort = linker.downcallHandle(
        linker.defaultLookup().find("qsort").get(),
        FunctionDescriptor.ofVoid(
            ValueLayout.ADDRESS,
            ValueLayout.JAVA_LONG,
            ValueLayout.JAVA_LONG,
            ValueLayout.ADDRESS));

    // A Java description of a C function implemented by a Java method
    final static FunctionDescriptor qsortCompareDesc = FunctionDescriptor.of(
        ValueLayout.JAVA_INT,
        ValueLayout.ADDRESS.asUnbounded(),
        ValueLayout.ADDRESS.asUnbounded());

    // Create method handle for qsortCompare
    final static MethodHandle compareHandle;
    static {
        try {   
            compareHandle = MethodHandles.lookup().findStatic(
                InvokeQsort.Qsort.class,
                "qsortCompare",
                qsortCompareDesc.toMethodType());
        } catch (Exception e) {
            throw new AssertionError(
                "Problem creating method handle compareHandle", e);
        }
    }    
    
    static int[] qsortTest(int[] unsortedArray) throws Throwable {
        
        int[] sorted = null;        
        
        try (Arena arena = Arena.openConfined()) {                    
        
            // Allocate off-heap memory and store unsortedArray in it                
            MemorySegment array = arena.allocateArray(
                                          ValueLayout.JAVA_INT,
                                          unsortedArray);        
        
            // Create function pointer for qsortCompare
            MemorySegment compareFunc = linker.upcallStub(
                compareHandle,
                qsortCompareDesc,
                arena.scope());
                    
            // Call qsort        
            qsort.invoke(array, (long)unsortedArray.length,
                ValueLayout.JAVA_INT.byteSize(), compareFunc);
            
            // Access off-heap memory
            sorted = array.toArray(ValueLayout.JAVA_INT);                
        }
        return sorted;
    }        
    
    public static void main(String[] args) {
        try { 
            int[] sortedArray = InvokeQsort.qsortTest(
                new int[] { 0, 9, 3, 4, 6, 5, 1, 8, 2, 7 });
            for (int num : sortedArray) {
                System.out.print(num + " ");
            }
            System.out.println();
        } catch (Throwable t) {
            t.printStackTrace();
        }
    }
}

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

    class Qsort {
        static int qsortCompare(MemorySegment addr1, MemorySegment addr2) {
            return addr1.get(ValueLayout.JAVA_INT, 0) - addr2.get(ValueLayout.JAVA_INT, 0);
        }
    }

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

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

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

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

    // A Java description of a C function implemented by a Java method
    final static FunctionDescriptor qsortCompareDesc = FunctionDescriptor.of(
        ValueLayout.JAVA_INT,
        ValueLayout.ADDRESS.asUnbounded(),
        ValueLayout.ADDRESS.asUnbounded());
    // Create method handle for qsortCompare
    final static MethodHandle compareHandle;
    static {
        try {   
            compareHandle = MethodHandles.lookup().findStatic(
                InvokeQsort.Qsort.class,
                "qsortCompare",
                qsortCompareDesc.toMethodType());
        } catch (Exception e) {
            throw new AssertionError(
                "Problem creating method handle compareHandle", e);
        }
    }

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

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

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

        try (Arena arena = Arena.openConfined()) {                    
        
            // Allocate off-heap memory and store unsortedArray in it                
            MemorySegment array = arena.allocateArray(
                                          ValueLayout.JAVA_INT,
                                          unsortedArray);

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

            // Create function pointer for qsortCompare
            MemorySegment compareFunc = linker.upcallStub(
                compareHandle,
                qsortCompareDesc,
                arena.scope());

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

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

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

            // Call qsort        
            qsort.invoke(array, (long)unsortedArray.length,
                ValueLayout.JAVA_INT.byteSize(), compareFunc);

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

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

            // Access off-heap memory
            sorted = array.toArray(ValueLayout.JAVA_INT);;   

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

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

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

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

        try (Arena arena = Arena.openConfined()) {

            MemorySegment segment =
                arena.allocate((long)(2 * 4 * 10), 1);

            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
            }
            // ...
        }

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

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

        try (Arena arena = Arena.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 = arena.allocate(ptsLayout);
            
            for (int i = 0; i < ptsLayout.elementCount(); i++) {
                xHandle.set(segment, (long) i, i);
                yHandle.set(segment, (long) i, i);
            }
            // ...
        }

最初の文によって、SequenceLayoutオブジェクトで表されるシーケンス・メモリー・レイアウトが作成されます。これには、StructLayoutオブジェクトで表される10個の構造体レイアウトのシーケンスが含まれます。メソッドMemoryLayout::structLayoutは、StructLayoutオブジェクトを返します。各構造体レイアウトには、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のようにメモリーにアクセスします。この例では、値(3番目の引数)がメモリー・セグメント(最初の引数)のインデックス(2番目の引数)に設定されます。VarHandle xHandleおよびyHandleは、Point構造体のサイズ(8バイト)とそのintメンバーのサイズ(4バイト)を認識しています。つまり、setAtIndexメソッドのように、配列の要素またはメモリー・アドレス・オフセットに必要なバイト数を計算する必要はありません。

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

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

実行するアプリケーションで、次に示す制限されたメソッドのいずれかが呼び出されると、Javaランタイムによって警告メッセージが出力されます:モジュールMのコードで、これらの制限されたメソッドまたは安全でないメソッドを警告が表示されずに使用できるようにするには、--enable-native-access=Mコマンドライン・オプションを指定します。複数のモジュールはカンマ区切りリストで指定します。クラス・パス上のすべてのコードで警告なしの使用を可能にするには、--enable-native-access=ALL-UNNAMEDオプションを指定します。

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

次のサイトからツールを入手します:

https://jdk.java.net/jextract/

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

https://github.com/openjdk/jextract

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