モジュール jdk.incubator.foreign
パッケージ jdk.incubator.foreign

インタフェースCLinker

public sealed interface CLinker
Cリンカーは、Cアプリケーション二項インタフェースの(ABI)呼び出し規則を実装します。 このインタフェースのインスタンスは、JVMターゲット・プラットフォームC ABIに準拠するネイティブ・ライブラリの外部ファンクションをリンクするために使用できます。

外部ファンクションのリンクは、2つのコンポーネントを必要とするプロセスです: メソッド型と関数記述子。 メソッド・タイプは、「通信事業者」タイプのセットで構成されており、これらを組み合せて、基礎となる外部ファンクションをコールする際にクライアントが準拠する必要があるJavaシグネチャを指定します。 ファンクション記述子には、リンクを実行できるように、外部ファンクションのシグネチャと分類情報(カスタム・レイアウト属性を使用,CLinker.TypeKindを参照)を一緒に指定するメモリー・レイアウトのセットが含まれています。

このAPIのクライアントは、このインタフェースにある事前定義済のメモリー・レイアウト定数(C言語で提供される組込み型のサブセットに基づく)を使用して関数記述子を構築できます。または、必要なCLinker.TypeKind分類属性(これは、MemoryLayout.withAttribute(String, Constable)メソッドを使用して実行できます)を使用して既存の値レイアウトを修飾することもできます。 そのようにしないと、リンクで外部ファンクション・コール中に引数をレジスタにロードする方法などを決定するために追加の分類情報が必要になる場合に、リンケージ・エラーが発生する可能性があります。

このインタフェースの実装では、次のプリミティブ・キャリア・タイプがサポートされます: byte, short, char, int, long, float、double、ポインタを渡すMemoryAddress、および構造体と共用体を渡すMemorySegment。 最後に、CLinker.VaListキャリア・タイプを使用して、ネイティブva_listタイプと一致させることができます。

リンク・プロセスを正常に実行するには、いくつかの要件を満たす必要があります。MおよびFがメソッド・タイプ(プレフィクス引数の削除後に取得)で、関数記述子がそれぞれリンク・プロセス中に使用される場合、その要件を満たす必要があります:

  • Mの引数は、Fの引数と同じです
  • Mの戻り型がvoidの場合、Fには戻りレイアウト(FunctionDescriptor.ofVoid(MemoryLayout...)を参照してください)を設定しないでください
  • MおよびFのキャリア・タイプCとレイアウトLのペアごとに、CとLが同じ引数または戻り値を参照する場合、次の条件を満たす必要があります:
    • Cがプリミティブ型の場合、LはValueLayoutである必要があり、レイアウトのサイズはキャリア型(Integer.SIZEおよび他のプリミティブ・ラッパー・クラスの類似フィールドを参照)のサイズと一致する必要があります
    • CがMemoryAddress.classの場合、LはValueLayoutである必要があり、そのサイズはプラットフォームのアドレス・サイズ(MemoryLayouts.ADDRESSを参照してください)と一致する必要があります。 このために、C_POINTERレイアウト定数を使用できます
    • CがMemorySegment.classの場合、LはGroupLayoutである必要があります
    • CがVaList.classの場合、LはC_VA_LISTである必要があります

仮パラメータ・リストの最後に末尾に省略記号(...)を付けるか、空の仮パラメータ・リストを使用してCで宣言された可変関数は、直接サポートされません。 可変数の引数を取るメソッド・ハンドルを作成することはできず、可変数の引数を受け入れるメソッド・ハンドルをラップするアップ・コール・スタブを作成することもできません。 ただし、ダウン・コールの場合のみ、「特殊化」メソッド型および関数記述子を使用してネイティブの可変関数をリンクできます: 可変引数として渡される引数ごとに、リンカーに渡されるメソッド型および関数記述子オブジェクトに、明示的で追加のキャリア型とメモリー・レイアウトが存在する必要があります。 さらに、関数記述子の可変引数に対応するメモリー・レイアウトには追加の分類情報が含まれている必要があるため、asVarArg(MemoryLayout)を使用して、特殊な関数記述子の可変引数に対応する各パラメータのメモリー・レイアウトを作成する必要があります。

サポートされていないプラットフォームでは、このクラスはExceptionInInitializerErrorでの初期化に失敗します。

特に指定がないかぎり、null引数、またはこのクラスのメソッドに1つ以上のnull要素を含む配列引数を渡すと、NullPointerExceptionがスローされます。

実装要件:
このインタフェースの実装は不変、スレッド・セーフ、およびvalue-basedです。

  • ネストされたクラスのサマリー

    ネストされたクラス
    修飾子と型
    インタフェース
    説明
    static enum 
    CLinker.TypeKind
    C型のタイプです。
    static interface 
    CLinker.VaList
    C va_listをモデル化するインタフェース。

  • フィールドのサマリー

    フィールド
    修飾子と型
    フィールド
    説明
    static final ValueLayout
    C_CHAR
    char C型のレイアウト
    static final ValueLayout
    C_DOUBLE
    double C型のレイアウト
    static final ValueLayout
    C_FLOAT
    float C型のレイアウト
    static final ValueLayout
    C_INT
    int C型のレイアウト
    static final ValueLayout
    C_LONG
    long C型のレイアウト
    static final ValueLayout
    C_LONG_LONG
    long long C型のレイアウト。
    static final ValueLayout
    C_POINTER
    T*ネイティブ型。
    static final ValueLayout
    C_SHORT
    short C型のレイアウト
    static final MemoryLayout
    C_VA_LIST
    va_list C型のレイアウト

  • メソッドのサマリー

    修飾子と型
    メソッド
    説明
    static MemoryAddress
    allocateMemory(long size)
    mallocを使用して、指定されたサイズのメモリーを割り当てます。
    static <T extends MemoryLayout>
    T
    asVarArg(T layout)
    特殊な関数記述子で可変引数のレイアウトとして使用するのに適したメモリー・レイアウトを返します。
    MethodHandle
    downcallHandle(MethodType type, FunctionDescriptor function)
    指定された型を持つ外部メソッド・ハンドルを取得し、指定された関数記述子を特徴とします。この記述子は、アドレスのターゲット外部関数をコールするために使用できます。
    MethodHandle
    downcallHandle(Addressable symbol, MethodType type, FunctionDescriptor function)
    指定された型を持つ外部メソッド・ハンドルを取得し、指定された関数記述子を特徴とします。この記述子は、指定されたアドレスのターゲット外部関数をコールするために使用できます。
    MethodHandle
    downcallHandle(Addressable symbol, SegmentAllocator allocator, MethodType type, FunctionDescriptor function)
    指定された型を持つ外部メソッド・ハンドルを取得し、指定された関数記述子を特徴とします。この記述子は、指定されたアドレスでターゲットの外部関数を呼び出すために使用できます。
    static void
    freeMemory(MemoryAddress addr)
    指定されたメモリー・アドレスが指すメモリーを解放します。
    static CLinker
    getInstance()
    現在のプラットフォームのCリンカーを返します。
    static SymbolLookup
    systemLookup()
    標準Cライブラリ内のシンボルを検索するのに適したシステム・ルックアップを取得します。
    static MemorySegment
    toCString(String str, ResourceScope scope)
    Java文字列をUTF-8エンコードされたnull終端のC文字列に変換し、指定されたリソース・スコープに関連付けられたネイティブ・メモリー・セグメントに結果を格納します。
    static MemorySegment
    toCString(String str, SegmentAllocator allocator)
    Java文字列をUTF-8エンコードされたnull終端のC文字列に変換し、指定されたロケータを使用して割り当てられたネイティブ・メモリー・セグメントに結果を格納します。
    static String
    toJavaString(MemoryAddress addr)
    指定されたアドレスに格納されているUTF-8エンコードされたnull終端のC文字列をJava文字列に変換します。
    static String
    toJavaString(MemorySegment addr)
    指定されたアドレスに格納されているUTF-8エンコードされたnull終端のC文字列をJava文字列に変換します。
    MemoryAddress
    upcallStub(MethodHandle target, FunctionDescriptor function, ResourceScope scope)
    指定されたスコープを持つネイティブ・スタブを、他の外部関数(関数ポインタとして)に渡すことができます。このようなファンクション・ポインタをネイティブ・コードからコールすると、指定されたメソッド・ハンドルが実行されます。

  • フィールド詳細

    • C_CHAR

      static final ValueLayout C_CHAR
      char C型のレイアウト

    • C_SHORT

      static final ValueLayout C_SHORT
      short C型のレイアウト

    • C_INT

      static final ValueLayout C_INT
      int C型のレイアウト

    • C_LONG

      static final ValueLayout C_LONG
      long C型のレイアウト

    • C_LONG_LONG

      static final ValueLayout C_LONG_LONG
      long long C型のレイアウト。

    • C_FLOAT

      static final ValueLayout C_FLOAT
      float C型のレイアウト

    • C_DOUBLE

      static final ValueLayout C_DOUBLE
      double C型のレイアウト

    • C_POINTER

      static final ValueLayout C_POINTER
      T*ネイティブ型。

    • C_VA_LIST

      static final MemoryLayout C_VA_LIST
      va_list C型のレイアウト

  • メソッドの詳細

    • getInstance

      static CLinker getInstance()
      現在のプラットフォームのCリンカーを返します。

      このメソッドは「制限付き」です。 制限されたメソッドは安全ではなく、誤って使用するとJVMがクラッシュしたり、悪化したりするとメモリーが破損する可能性があります。 したがって、クライアントは制限付きメソッドに応じて屈折し、可能な場合は安全でサポートされている機能を使用する必要があります。

      戻り値:
      このシステムのリンカー。
      例外:
      IllegalCallerException - このメソッドへのアクセスがモジュールMから発生し、コマンドライン・オプション--enable-native-accessがない場合、またはモジュール名Mが名前なしモジュールの場合はALL-UNNAMEDは説明しません。

    • systemLookup

      static SymbolLookup systemLookup()
      標準Cライブラリ内のシンボルを検索するのに適したシステム・ルックアップを取得します。 ルックアップに使用できる記号のセットは、プラットフォームおよびオペレーティング・システムに依存するため、指定されていません。

      このメソッドは「制限付き」です。 制限されたメソッドは安全ではなく、誤って使用するとJVMがクラッシュしたり、悪化したりするとメモリーが破損する可能性があります。 したがって、クライアントは制限付きメソッドに応じて屈折し、可能な場合は安全でサポートされている機能を使用する必要があります。

      戻り値:
      標準Cライブラリ内のシンボルを検索するのに適した、システム固有のライブラリ・ルックアップ。
      例外:
      IllegalCallerException - このメソッドへのアクセスがモジュールMから発生し、コマンドライン・オプション--enable-native-accessがない場合、またはモジュール名Mが名前なしモジュールの場合はALL-UNNAMEDは説明しません。

    • downcallHandle

      MethodHandle downcallHandle(Addressable symbol, MethodType type, FunctionDescriptor function)
      指定された型を持つ外部メソッド・ハンドルを取得し、指定された関数記述子を特徴とします。この記述子は、指定されたアドレスのターゲット外部関数をコールするために使用できます。

      指定されたメソッド・タイプの戻り型がMemorySegmentの場合、結果のメソッド・ハンドルは、タイプSegmentAllocatorの追加のプレフィクス・パラメータを特徴づけます。これは、リンカー・ランタイムが値によって返される構造を割り当てるために使用されます。

      パラメータ:
      symbol - downcallシンボル。
      type - メソッド・タイプ。
      function - 関数記述子。
      戻り値:
      downcallメソッド・ハンドル。
      例外:
      IllegalArgumentException - メソッド・タイプおよび関数記述子が一致しない場合、または記号がMemoryAddress.NULLの場合
      関連項目:

    • downcallHandle

      MethodHandle downcallHandle(Addressable symbol, SegmentAllocator allocator, MethodType type, FunctionDescriptor function)
      指定された型を持つ外部メソッド・ハンドルを取得し、指定された関数記述子を特徴とします。この記述子は、指定されたアドレスでターゲットの外部関数を呼び出すために使用できます。

      指定されたメソッド・タイプの戻り型がMemorySegmentの場合、指定されたロケータは、指定されたロケータを使用して、値で返された構造体を割り当てます。

      パラメータ:
      symbol - downcallシンボル。
      allocator - ロケータ。
      type - メソッド・タイプ。
      function - 関数記述子。
      戻り値:
      downcallメソッド・ハンドル。
      例外:
      IllegalArgumentException - メソッド・タイプおよび関数記述子が一致しない場合、または記号がMemoryAddress.NULLの場合
      関連項目:

    • downcallHandle

      MethodHandle downcallHandle(MethodType type, FunctionDescriptor function)
      指定された型を持つ外部メソッド・ハンドルを取得し、指定された関数記述子を特徴とします。この記述子は、アドレスのターゲット外部関数をコールするために使用できます。 結果のメソッド・ハンドルには、Addressable型のアドレスに対応するプレフィクス・パラメータ(最初のパラメータとして)があります。

      指定されたメソッド・タイプの戻り型がMemorySegmentの場合、結果のメソッド・ハンドルには、SegmentAllocator型の追加のプレフィクス・パラメータ(アドレス・パラメータの直後に挿入)(タイプSegmentAllocator)が備えられ、これにより、リンカー・ランタイムによって返される構造が割り当てられます。

      返されるメソッド・ハンドルは、渡されたターゲット・アドレスがMemoryAddress.NULLの場合はIllegalArgumentExceptionを、ターゲット・アドレスがnullの場合はNullPointerExceptionをスローします。

      パラメータ:
      type - メソッド・タイプ。
      function - 関数記述子。
      戻り値:
      downcallメソッド・ハンドル。
      例外:
      IllegalArgumentException - メソッド型と関数記述子が一致しない場合。
      関連項目:

    • upcallStub

      MemoryAddress upcallStub(MethodHandle target, FunctionDescriptor function, ResourceScope scope)
      指定されたスコープを持つネイティブ・スタブを、他の外部関数(関数ポインタとして)に渡すことができます。このようなファンクション・ポインタをネイティブ・コードからコールすると、指定されたメソッド・ハンドルが実行されます。

      返されるメモリー・アドレスは、指定されたスコープに関連付けられます。 このようなスコープが閉じられると、対応するネイティブ・スタブが割り当て解除されます。

      ターゲット・メソッド・ハンドルは例外をスローしません。 ターゲット・メソッド・ハンドルが例外をスローすると、VMはゼロ以外の終了コードで終了します。 例外の捕捉が原因でVMが中断しないように、クライアントは、Throwableを捕捉するtry/catchブロック内のターゲット・メソッド・ハンドル内のすべてのコードをラップできます。たとえば、MethodHandles.catchException(MethodHandle, Class, MethodHandle)メソッド・ハンドル・コンビネータを使用し、対応するcatchブロックで必要に応じて例外を処理します。

      パラメータ:
      target - ターゲット・メソッド・ハンドル。
      function - 関数記述子。
      scope - upcallスタブ・スコープ。
      戻り値:
      ネイティブ・スタブ・セグメント。
      例外:
      IllegalArgumentException - ターゲット・メソッド・タイプと関数記述子が一致しない場合。
      IllegalStateException - scopeがすでにクローズされている場合、またはscopeを所有するスレッド以外のスレッドからアクセスが発生した場合。

    • asVarArg

      static <T extends MemoryLayout> T asVarArg(T layout)
      特殊な関数記述子で可変引数のレイアウトとして使用するのに適したメモリー・レイアウトを返します。
      型パラメータ:
      T - メモリー・レイアウト・タイプ
      パラメータ:
      layout - 適応するレイアウト
      戻り値:
      適切な属性を持つ新しく作成された可能性のあるレイアウト

    • toCString

      static MemorySegment toCString(String str, SegmentAllocator allocator)
      Java文字列をUTF-8エンコードされたnull終端のC文字列に変換し、指定されたロケータを使用して割り当てられたネイティブ・メモリー・セグメントに結果を格納します。

      このメソッドは、不正入力シーケンスやマップ不可文字シーケンスを、この文字セットのデフォルトの置換バイト配列で置き換えます。 エンコード処理をより強力に制御する必要がある場合は、CharsetEncoderクラスを使用してください。

      パラメータ:
      str - C文字列に変換するJava文字列。
      allocator - ネイティブ・セグメント割り当てに使用するロケータ。
      戻り値:
      変換されたC文字列を含む新しいネイティブ・メモリー・セグメント。

    • toCString

      static MemorySegment toCString(String str, ResourceScope scope)
      Java文字列をUTF-8エンコードされたnull終端のC文字列に変換し、指定されたリソース・スコープに関連付けられたネイティブ・メモリー・セグメントに結果を格納します。

      このメソッドは、不正入力シーケンスやマップ不可文字シーケンスを、この文字セットのデフォルトの置換バイト配列で置き換えます。 エンコード処理をより強力に制御する必要がある場合は、CharsetEncoderクラスを使用してください。

      パラメータ:
      str - C文字列に変換するJava文字列。
      scope - 返されるセグメントに関連付けるリソース・スコープ。
      戻り値:
      変換されたC文字列を含む新しいネイティブ・メモリー・セグメント。
      例外:
      IllegalStateException - scopeがすでにクローズされている場合、またはscopeを所有するスレッド以外のスレッドからアクセスが発生した場合。

    • toJavaString

      static String toJavaString(MemoryAddress addr)
      指定されたアドレスに格納されているUTF-8エンコードされたnull終端のC文字列をJava文字列に変換します。

      このメソッドは、不正入力シーケンスやマップ不可文字シーケンスを、この文字セットのデフォルトの置換文字列で置き換えます。 デコード処理をより強力に制御する必要がある場合、CharsetDecoderクラスを使用する必要があります。

      このメソッドは「制限付き」です。 制限されたメソッドは安全ではなく、誤って使用するとJVMがクラッシュしたり、悪化したりするとメモリーが破損する可能性があります。 したがって、クライアントは制限付きメソッドに応じて屈折し、可能な場合は安全でサポートされている機能を使用する必要があります。

      パラメータ:
      addr - 文字列が格納されるアドレス。
      戻り値:
      指定されたアドレスにある、空文字で終わるC文字列の内容を含むJava文字列。
      例外:
      IllegalArgumentException - ネイティブ文字列のサイズがプラットフォームでサポートされる最大文字列より大きい場合、またはaddr == MemoryAddress.NULLの場合。
      IllegalCallerException - このメソッドへのアクセスがモジュールMから発生し、コマンドライン・オプション--enable-native-accessがない場合、またはモジュール名Mが名前なしモジュールの場合はALL-UNNAMEDは説明しません。

    • toJavaString

      static String toJavaString(MemorySegment addr)
      指定されたアドレスに格納されているUTF-8エンコードされたnull終端のC文字列をJava文字列に変換します。

      このメソッドは、不正入力シーケンスやマップ不可文字シーケンスを、この文字セットのデフォルトの置換文字列で置き換えます。 デコード処理をより強力に制御する必要がある場合、CharsetDecoderクラスを使用する必要があります。

      パラメータ:
      addr - 文字列が格納されるアドレス。
      戻り値:
      指定されたアドレスにある、空文字で終わるC文字列の内容を含むJava文字列。
      例外:
      IllegalArgumentException - ネイティブ文字列のサイズがプラットフォームでサポートされている最大文字列より大きい場合。
      IllegalStateException - ネイティブ文字列のサイズがaddrに関連付けられたセグメントのサイズより大きい場合、またはaddrが「生きていない」のセグメントに関連付けられている場合。

    • allocateMemory

      static MemoryAddress allocateMemory(long size)
      mallocを使用して、指定されたサイズのメモリーを割り当てます。

      このメソッドは「制限付き」です。 制限されたメソッドは安全ではなく、誤って使用するとJVMがクラッシュしたり、悪化したりするとメモリーが破損する可能性があります。 したがって、クライアントは制限付きメソッドに応じて屈折し、可能な場合は安全でサポートされている機能を使用する必要があります。

      パラメータ:
      size - 割り当てるメモリー・サイズ
      戻り値:
      addr割り当てられたメモリーのメモリー・アドレス
      例外:
      OutOfMemoryError - mallocが必要な量のネイティブ・メモリーを割り当てられなかった場合。
      IllegalCallerException - このメソッドへのアクセスがモジュールMから発生し、コマンドライン・オプション--enable-native-accessがない場合、またはモジュール名Mが名前なしモジュールの場合はALL-UNNAMEDは説明しません。

    • freeMemory

      static void freeMemory(MemoryAddress addr)
      指定されたメモリー・アドレスが指すメモリーを解放します。

      このメソッドは「制限付き」です。 制限されたメソッドは安全ではなく、誤って使用するとJVMがクラッシュしたり、悪化したりするとメモリーが破損する可能性があります。 したがって、クライアントは制限付きメソッドに応じて屈折し、可能な場合は安全でサポートされている機能を使用する必要があります。

      パラメータ:
      addr - 解放するネイティブ・メモリーのメモリー・アドレス
      例外:
      IllegalCallerException - このメソッドへのアクセスがモジュールMおよびコマンドライン・オプションから発生した場合
      IllegalArgumentException - if addr == MemoryAddress.NULL. --enable-native-accessは存在しないか、モジュール名MまたはALL-UNNAMEDは記述しません(Mが名前なしモジュールの場合)。