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

インタフェースCLinker

public 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がスローされます。

APIのノート:
将来、Java言語で許可される場合、CLinkerがsealedインタフェースになる可能性があり、明示的に許可されているタイプ以外はサブクラス化できなくなります。
実装要件:
このインタフェースの実装は不変、スレッド・セーフ、およびvalue-basedです。

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

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

  • フィールドのサマリー

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

  • メソッドのサマリー

    修飾子と型
    メソッド
    説明
    static MemoryAddress
    allocateMemoryRestricted​(long size)
    mallocを使用して、指定されたサイズのメモリーを割り当てます。
    static <T extends MemoryLayout>
    T
    asVarArg​(T layout)
    特殊な関数記述子で可変引数のレイアウトとして使用するのに適したメモリー・レイアウトを返します。
    MethodHandle
    downcallHandle​(Addressable symbol, MethodType type, FunctionDescriptor function)
    指定された型の外部メソッド・ハンドルを取得します。このハンドルを使用して、指定されたアドレスでターゲット外部ファンクションをコールし、指定されたファンクション記述子を指定できます。
    static void
    freeMemoryRestricted​(MemoryAddress addr)
    指定されたメモリー・アドレスが指すメモリーを解放します。
    static CLinker
    getInstance()
    現在のプラットフォームのCリンカーを返します。
    static MemorySegment
    toCString​(String str)
    プラットフォームのデフォルトの文字セットを使用して、Java文字列をNULLで終わるC文字列に変換し、結果を新しいネイティブ・メモリー・セグメントに格納します。
    static MemorySegment
    toCString​(String str, Charset charset)
    指定されたcharsetを使用して、Java文字列をNULLで終わるC文字列に変換し、結果を新しいネイティブ・メモリー・セグメントに格納します。
    static MemorySegment
    toCString​(String str, Charset charset, NativeScope scope)
    指定されたcharsetを使用して、Java文字列を空文字で終了するC文字列に変換し、指定されたスコープを使用して割り当てられた新しいネイティブ・メモリー・セグメント・ネイティブ・メモリー・セグメントに結果を格納します。
    static MemorySegment
    toCString​(String str, NativeScope scope)
    プラットフォームのデフォルトの文字セットを使用して、Java文字列を空文字で終了するC文字列に変換し、指定されたスコープを使用して割り当てられたネイティブ・メモリー・セグメントに結果を格納します。
    static String
    toJavaString​(MemorySegment addr)
    プラットフォームのデフォルトの文字セットを使用して、指定されたアドレスに格納されているNULLで終わるC文字列をJava文字列に変換します。
    static String
    toJavaString​(MemorySegment addr, Charset charset)
    指定されたcharsetを使用して、指定されたアドレスに格納されているNULLで終わるC文字列をJava文字列に変換します。
    static String
    toJavaStringRestricted​(MemoryAddress addr)
    プラットフォームのデフォルトの文字セットを使用して、指定されたアドレスに格納されているNULLで終わるC文字列をJava文字列に変換します。
    static String
    toJavaStringRestricted​(MemoryAddress addr, Charset charset)
    指定されたcharsetを使用して、指定されたアドレスに格納されているNULLで終わるC文字列をJava文字列に変換します。
    MemorySegment
    upcallStub​(MethodHandle target, FunctionDescriptor function)
    ベース・アドレス(MemorySegment.address()を参照してください)を他の外部ファンクション(関数ポインタとして)に渡すことができるネイティブ・セグメントを割り当てます。このようなファンクション・ポインタをネイティブ・コードからコールすると、指定されたメソッド・ハンドルが実行されます。

  • フィールド詳細

    • 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がクラッシュしたり、メモリーが警告なしで破損する可能性があります。 したがって、クライアントは制限付きメソッドに応じて屈折し、可能な場合は安全でサポートされている機能を使用する必要があります。

      戻り値:
      このシステムのリンカー。
      例外:
      IllegalAccessError - ランタイム・プロパティforeign.restrictedがpermit、warnまたはdebug (デフォルト値はdenyに設定されています)のいずれにも設定されていない場合。

    • downcallHandle

      MethodHandle downcallHandle​(Addressable symbol, MethodType type, FunctionDescriptor function)
      指定された型の外部メソッド・ハンドルを取得します。このハンドルを使用して、指定されたアドレスでターゲット外部ファンクションをコールし、指定されたファンクション記述子を指定できます。
      パラメータ:
      symbol - downcallシンボル。
      type - メソッド・タイプ。
      function - 関数記述子。
      戻り値:
      downcallメソッド・ハンドル。
      例外:
      IllegalArgumentException - メソッド型と関数記述子が一致しない場合。
      関連項目:
      LibraryLookup.lookup(String)

    • upcallStub

      MemorySegment upcallStub​(MethodHandle target, FunctionDescriptor function)
      ベース・アドレス(MemorySegment.address()を参照してください)を他の外部ファンクション(関数ポインタとして)に渡すことができるネイティブ・セグメントを割り当てます。このようなファンクション・ポインタをネイティブ・コードからコールすると、指定されたメソッド・ハンドルが実行されます。

      戻されるセグメントはsharedであり、MemorySegment.CLOSEアクセス・モードのみが特徴です。 返されたセグメントがクローズされると、対応するネイティブ・スタブの割当てが解除されます。

      パラメータ:
      target - ターゲット・メソッド・ハンドル。
      function - 関数記述子。
      戻り値:
      ネイティブ・スタブ・セグメント。
      例外:
      IllegalArgumentException - ターゲット・メソッド・タイプと関数記述子が一致しない場合。

    • asVarArg

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

    • toCString

      static MemorySegment toCString​(String str)
      プラットフォームのデフォルトの文字セットを使用して、Java文字列をNULLで終わるC文字列に変換し、結果を新しいネイティブ・メモリー・セグメントに格納します。

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

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

    • toCString

      static MemorySegment toCString​(String str, Charset charset)
      指定されたcharsetを使用して、Java文字列をNULLで終わるC文字列に変換し、結果を新しいネイティブ・メモリー・セグメントに格納します。

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

      パラメータ:
      str - C文字列に変換するJava文字列。
      charset - C文字列の内容のコンピュートに使用されるCharset。
      戻り値:
      変換されたC文字列を含む新しいネイティブ・メモリー・セグメント。

    • toCString

      static MemorySegment toCString​(String str, NativeScope scope)
      プラットフォームのデフォルトの文字セットを使用して、Java文字列を空文字で終了するC文字列に変換し、指定されたスコープを使用して割り当てられたネイティブ・メモリー・セグメントに結果を格納します。

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

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

    • toCString

      static MemorySegment toCString​(String str, Charset charset, NativeScope scope)
      指定されたcharsetを使用して、Java文字列を空文字で終了するC文字列に変換し、指定されたスコープを使用して割り当てられた新しいネイティブ・メモリー・セグメント・ネイティブ・メモリー・セグメントに結果を格納します。

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

      パラメータ:
      str - C文字列に変換するJava文字列。
      charset - C文字列の内容のコンピュートに使用されるCharset。
      scope - ネイティブ・セグメント割当てに使用されるスコープ。
      戻り値:
      変換されたC文字列を含む新しいネイティブ・メモリー・セグメント。

    • toJavaStringRestricted

      static String toJavaStringRestricted​(MemoryAddress addr)
      プラットフォームのデフォルトの文字セットを使用して、指定されたアドレスに格納されているNULLで終わるC文字列をJava文字列に変換します。

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

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

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

    • toJavaStringRestricted

      static String toJavaStringRestricted​(MemoryAddress addr, Charset charset)
      指定されたcharsetを使用して、指定されたアドレスに格納されているNULLで終わるC文字列をJava文字列に変換します。

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

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

      パラメータ:
      addr - 文字列が格納されるアドレス。
      charset - Java文字列の内容のコンピュートに使用されるCharset。
      戻り値:
      指定されたアドレスにある、空文字で終わるC文字列の内容を含むJava文字列。
      例外:
      IllegalArgumentException - ネイティブ文字列のサイズがプラットフォームでサポートされている最大文字列より大きい場合。

    • toJavaString

      static String toJavaString​(MemorySegment addr)
      プラットフォームのデフォルトの文字セットを使用して、指定されたアドレスに格納されているNULLで終わるC文字列をJava文字列に変換します。

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

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

    • toJavaString

      static String toJavaString​(MemorySegment addr, Charset charset)
      指定されたcharsetを使用して、指定されたアドレスに格納されているNULLで終わるC文字列をJava文字列に変換します。

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

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

    • allocateMemoryRestricted

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

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

      パラメータ:
      size - 割り当てるメモリー・サイズ
      戻り値:
      addr割り当てられたメモリーのメモリー・アドレス
      例外:
      OutOfMemoryError - mallocが必要な量のネイティブ・メモリーを割り当てられなかった場合。

    • freeMemoryRestricted

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

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

      パラメータ:
      addr - 解放するネイティブ・メモリーのメモリー・アドレス