モジュール java.base
パッケージ java.lang.foreign

インタフェースLinker.Option

含まれているインタフェース:
LinkerPREVIEW
public static sealed interface Linker.Option
Optionは、JavaプラットフォームのプレビューAPIです。
プレビュー機能が有効な場合のみ、プログラムでOptionを使用できます。
プレビュー機能は、今後のリリースで削除するか、Javaプラットフォームの永続機能にアップグレードすることができます。
リンカー・オプションは、リンケージ・リクエストに追加のパラメータを指定するために使用されます。
導入されたバージョン:
20

  • メソッドのサマリー

    静的メソッド
    修飾子と型
    メソッド
    説明
    static Linker.OptionPREVIEW
    captureCallState(String... capturedState)
    ダウンコール・メソッド・ハンドルに関連付けられた外部関数をコールした直後に実行状態の一部を保存するために使用するリンカー・オプションを返し、Javaランタイムで上書きしたり、従来の方法で読み取ることができます。
    static StructLayoutPREVIEW
    captureStateLayout()
    captureCallState(String...)でリンクされたダウンコール・ハンドルに渡される取得状態セグメントのレイアウトを表す構造体レイアウトを返します。
    static Linker.OptionPREVIEW
    firstVariadicArg(int index)
    ダウンコール・リンケージ・リクエストに関連付けられた関数記述子によって記述された関数に渡される可変個引数の開始を示す索引を示すために使用されるリンカー・オプションを返します。
    static Linker.OptionPREVIEW
    isTrivial()
    外部関数を「Trival」としてマークするために使用されるリンカー・オプションを返します。

  • メソッドの詳細

    • firstVariadicArg

      static Linker.OptionPREVIEW firstVariadicArg(int index)
      ダウンコール・リンケージ・リクエストに関連付けられた関数記述子によって記述された関数に渡される可変個引数の開始を示す索引を示すために使用されるリンカー・オプションを返します。

      index値は0 <= index <= Nに準拠する必要があります。ここで、Nは、このリンカー・オプションと組み合わせて使用される関数記述子の引数レイアウトの数です。 indexが次の場合:

      • 0。関数に渡されるすべての引数は、可変個引数として渡されます
      • N。関数に渡された引数はいずれも可変個引数として渡されません
      • n。0 < m < Nでは、引数m..Nは可変個引数として渡されます
      「可変個引数関数」をリンクするときは、可変個引数が (上のリストにある2番目のケース)に渡されない場合でも、常にこのリンカー・オプションを使用することが重要です。これは、特定のプラットフォームでの呼び出し規則に引き続き影響を与える可能性があるためです。

      実装上のノート:
      索引値は、リンク・リクエストを行うときに検証されます。リンク・リクエストは、索引が検証されるファンクション記述子が使用可能なときです。
      パラメータ:
      index - ダウンコール・リンケージ・リクエストに関連付けられた関数記述子内の最初の可変個引数レイアウトのインデックス。
      戻り値:
      ダウンコール・リンケージ・リクエストに関連付けられた関数記述子によって記述された関数に渡される可変個引数の開始を示す、インデックスを示すために使用されるリンカー・オプション

    • captureCallState

      static Linker.OptionPREVIEW captureCallState(String... capturedState)
      ダウンコール・メソッド・ハンドルに関連付けられた外部関数をコールした直後に実行状態の一部を保存するために使用するリンカー・オプションを返し、Javaランタイムで上書きしたり、従来の方法で読み取ることができます。

      実行状態は、ユーザーが提供したネイティブ・セグメントにダウン・コール・メソッド・ハンドルに書き込むことで、起動時のダウン・コール・メソッド・ハンドルによって取得されます。 このために、このオプションとリンクされたダウンコール・メソッド・ハンドルには、ターゲット・アドレスの直後の追加のMemorySegmentPREVIEWパラメータと、オプションのSegmentAllocatorPREVIEWパラメータがあります。 このパラメータ「状態セグメントの取得」は、取得された状態が書き込まれるネイティブ・セグメントを表します。

      取得状態セグメントのサイズと位置合せは、captureStateLayout()によって返されるレイアウトと互換性がある必要があります。 このレイアウトは、取得された各値の名前付きフィールドを持つ構造体のレイアウトです。

      取得された状態は、「状態レイアウトの取得」からvarハンドルを構築することで、取得状態セグメントから取得できます。

      次の例は、このリンカー・オプションの使用を示しています: 

      MemorySegment targetAddress = ...
Linker.Option ccs = Linker.Option.captureCallState("errno");
MethodHandle handle = Linker.nativeLinker().downcallHandle(targetAddress, FunctionDescriptor.ofVoid(), ccs);

StructLayout capturedStateLayout = Linker.Option.captureStateLayout();
VarHandle errnoHandle = capturedStateLayout.varHandle(PathElement.groupElement("errno"));
try (Arena arena = Arena.ofConfined()) {
    MemorySegment capturedState = arena.allocate(capturedStateLayout);
    handle.invoke(capturedState);
    int errno = (int) errnoHandle.get(capturedState);
    // use errno
}

      パラメータ:
      capturedState - 保存する値の名前。
      戻り値:
      ダウンコール・メソッド・ハンドルに関連付けられた外部関数をコールした直後に実行状態の一部を保存するために使用するリンカー・オプション。Javaランタイムで上書きしたり、従来の方法で読み取ることができます
      例外:
      IllegalArgumentException - 指定されたcapturedState名の少なくとも1つが現在のプラットフォームでサポートされていない場合。
      関連項目:

    • captureStateLayout

      static StructLayoutPREVIEW captureStateLayout()
      captureCallState(String...)でリンクされたダウンコール・ハンドルに渡される取得状態セグメントのレイアウトを表す構造体レイアウトを返します。

      取得状態レイアウトはplatform-dependentですが、「値レイアウト」PREVIEWのみを含む「構造体レイアウト」PREVIEW、および場合によっては「パディング・レイアウト」PREVIEWであることが保証されます。 たとえば、Windowsでは、返されるレイアウトに次の3つの値レイアウトが含まれる場合があります:

      • GetLastError
      • WSAGetLastError
      • errno

      クライアントは、サポートされている取得値レイアウトの名前を次のように取得できます: 

         List<String> capturedNames = Linker.Option.captureStateLayout().memberLayouts().stream()
       .map(MemoryLayout::name)
       .flatMap(Optional::stream)
       .toList();

      戻り値:
      captureCallState(String...)でリンクされたダウンコール・ハンドルに渡される取得状態セグメントのレイアウトを表す構造体レイアウト
      関連項目:

    • isTrivial

      static Linker.OptionPREVIEW isTrivial()
      外部関数を「Trival」としてマークするために使用されるリンカー・オプションを返します。

      簡単な関数は、すべてのケースで(空の関数のコールに似ています)の実行時間が非常に短い関数であり、Java (例、アップコール・スタブの使用)へのコールは実行されません。

      このリンカー・オプションの使用は、いくつかの実装で、簡単な関数に対してのみ有効な最適化を適用するために使用できるヒントです。

      非簡易関数をリンクするときにこのリンカー・オプションを使用すると、パフォーマンスの損失やJVMのクラッシュなどの悪影響が生じる可能性があります。

      戻り値:
      外部関数を「Trival」としてマークするために使用されるリンカー・オプション