モジュール java.base

パッケージ java.lang.foreign

インタフェースLinker.Option

含まれているインタフェース:

Linker

public static sealed interface Linker.Option

リンカー・オプションは、リンケージ・リクエストに追加のパラメータを指定するために使用されます。

導入されたバージョン:

22

メソッドのサマリー

静的メソッド

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

メソッドの詳細

firstVariadicArg

static Linker.Option firstVariadicArg(int index)

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

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

• 0。関数に渡されるすべての引数は、可変個引数として渡されます
• N。関数に渡された引数はいずれも可変個引数として渡されません
• n。0 < m < Nでは、引数m..Nは可変個引数として渡されます

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

実装上のノート:

索引値は、リンク・リクエストを行うときに検証されます。リンク・リクエストは、索引が検証されるファンクション記述子が使用可能なときです。

パラメータ:

index - ダウンコール・リンケージ・リクエストに関連付けられた関数記述子内の最初の可変個引数レイアウトのインデックス

戻り値:

ダウンコール・リンケージ・リクエストに関連付けられた関数記述子によって記述された関数に渡される可変個引数の開始を示す、インデックスを示すために使用されるリンカー・オプション

captureCallState

static Linker.Option captureCallState(String... capturedState)

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

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

取得状態セグメントのサイズと位置合せは、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
}

このリンカー・オプションはcritical(boolean)と組み合わせることはできません。

パラメータ:

capturedState - 保存する値の名前

戻り値:

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

例外:

IllegalArgumentException - 指定されたcapturedState名の少なくとも1つが現在のプラットフォームでサポートされていない場合

関連項目:

• captureStateLayout()

captureStateLayout

static StructLayout captureStateLayout()

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

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

• GetLastError
• WSAGetLastError
• errno

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

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

戻り値:

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

関連項目:

• captureCallState(String...)

critical

static Linker.Option critical(boolean allowHeapAccess)

外部関数をcriticalとしてマークするために使用されるリンカー・オプションを返します。

クリティカル・ファンクションは、すべてのケースで(空の関数のコールに似ています)の実行時間が非常に短く、Java (例、アップ・コール・スタブの使用)をコールバックしないファンクションです。

このリンカー・オプションを使用することは、一部の実装で、重要な機能にのみ有効な最適化を適用するために使用できるヒントです。

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

クリティカル関数は、オプションでJavaヒープへのアクセスを許可できます。 これにより、クライアントはヒープ・メモリー・セグメントをアドレスとして渡すことができ、通常はオフ・ヒープ・メモリー・セグメントのみが許可されます。 Javaヒープ内のメモリー・リージョンは、ファンクション・コール中に有効な一時ネイティブ・アドレスを介して公開されます。 したがって、このメカニズムの使用は、ファンクションがJavaヒープ・メモリーに短期間アクセスする必要があり、関連するデータをオフ・ヒープ・メモリー・セグメントにコピーすることがパフォーマンスに関して禁止される場合にのみ推奨されます。

パラメータ:

allowHeapAccess - リンクされた関数がJavaヒープへのアクセスを許可するかどうか。

戻り値:

外部関数をcriticalとしてマークするために使用されるリンカー・オプション