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

インタフェースSymbolLookup

関数型インタフェース:
これは関数型インタフェースなので、ラムダ式またはメソッド参照の代入先として使用できます。
@FunctionalInterface public interface SymbolLookup
SymbolLookupは、JavaプラットフォームのプレビューAPIです。
プレビュー機能が有効な場合のみ、プログラムでSymbolLookupを使用できます。
プレビュー機能は、今後のリリースで削除するか、Javaプラットフォームの永続機能にアップグレードすることができます。
「シンボル・ルックアップ」は、1つ以上のライブラリ内のシンボルのアドレスを取得します。 シンボルは、関数やグローバル変数などの名前付きエンティティです。

シンボル・ルックアップは、特定のライブラリ (またはライブラリ)に対して作成されます。 その後、find(String)メソッドはシンボルの名前を取得し、そのライブラリ内のシンボルのアドレスを返します。

シンボルのアドレスは、長さゼロの「メモリー・セグメント」PREVIEWとしてモデル化されます。 セグメントは次の様々な方法で使用できます:

  • これは、LinkerPREVIEWに渡してダウン・コール・メソッド・ハンドルを作成でき、これを使用してセグメントのアドレスで外部関数をコールできます。
  • 既存の「ダウンコール・メソッド・ハンドル」PREVIEWに、基礎となる外部関数の引数として渡すことができます。
  • 別のメモリー・セグメント内の「保管済み」PREVIEWにできます。
  • グローバル変数(最初にresizingPREVIEWセグメントが必要になる場合があります)をバッキングするメモリー・リージョンにアクセスするために使用できます。

シンボル・ルックアップの取得

ファクトリ・メソッドlibraryLookup(String, SegmentScope)およびlibraryLookup(Path, SegmentScope)は、オペレーティング・システムで認識されているライブラリのシンボル・ルックアップを作成します。 ライブラリは、その名前またはパスで指定されます。 ライブラリがまだロードされていない場合はロードされます。 「ライブラリ・ルックアップ」と呼ばれるシンボル検索は、scopePREVIEWに関連付けられます。スコープがSegmentScope.isAlive()PREVIEWではなくなると、ライブラリはアンロードされます: 
 try (Arena arena = Arena.openConfined()) {
     SymbolLookup libGL = SymbolLookup.libraryLookup("libGL.so", arena.scope()); // libGL.so loaded here
     MemorySegment glGetString = libGL.find("glGetString").orElseThrow();
     ...
 } //  libGL.so unloaded here

以前にSystem.load(String)またはSystem.loadLibrary(String)によってJNI、i.eを介してライブラリがロードされていた場合、ライブラリは特定のクラス・ローダーにも関連付けられていました。 ファクトリ・メソッドloaderLookup()は、コール元クラス・ローダーに関連付けられたすべてのライブラリのシンボル・ルックアップを作成します: 

System.loadLibrary("GL"); // libGL.so loaded here
...
SymbolLookup libGL = SymbolLookup.loaderLookup();
MemorySegment glGetString = libGL.find("glGetString").orElseThrow();
このシンボル・ルックアップは「ローダー・ルックアップ」と呼ばれ、クラス・ローダーに関連付けられたライブラリに関して動的です。 その後、他のライブラリがJNIを介してロードされ、クラス・ローダーに関連付けられている場合、ローダー・ルック・アッ・ルックアッププではそのシンボルが自動的に公開されます。

ローダー・ルックアップでは、System.load(String)またはSystem.loadLibrary(String)によって以前にJNI、i.eを介してロードされたライブラリ内の記号のみが公開されることに注意してください。 ローダー・ルックアップでは、ライブラリ・ルックアップの作成中にロードされたライブラリ内のシンボルは公開されません: 

 libraryLookup("libGL.so", scope).find("glGetString").isPresent(); // true
 loaderLookup().find("glGetString").isPresent(); // false
ライブラリLのライブラリ・ルックアップでは、Lが以前にJNI (クラス・ローダーとの関連付けはライブラリ・ルックアップにとって重要ではありません)を介してロードされている場合でも、Lのシンボルが公開されることにも注意してください: 
 System.loadLibrary("GL"); // libGL.so loaded here
 libraryLookup("libGL.so", scope).find("glGetString").isPresent(); // true

最後に、各LinkerPREVIEWは、そのLinkerPREVIEWでサポートされるOSとプロセッサの組合せで一般的に使用されるライブラリのシンボル・ルックアップを提供します。 このシンボル・ルックアップは「デフォルト・ルックアップ」と呼ばれ、クライアントが既知のシンボルのアドレスをすばやく検索するのに役立ちます。 たとえば、Linux/x64のLinkerPREVIEWは、デフォルト・ルックアップを介してlibcのシンボルを公開することを選択できます: 

 Linker nativeLinker = Linker.nativeLinker();
 SymbolLookup stdlib = nativeLinker.defaultLookup();
 MemorySegment malloc = stdlib.find("malloc").orElseThrow();

  • メソッドのサマリー

    修飾子と型
    メソッド
    説明
    Optional<MemorySegmentPREVIEW>
    find(String name)
    指定された名前のシンボルのアドレスを返します。
    static SymbolLookupPREVIEW
    libraryLookup(String name, SegmentScopePREVIEW scope)
    指定された名前 (まだロードされていない場合)のライブラリをロードし、そのライブラリ内のシンボルのシンボル・ルックアップを作成します。
    static SymbolLookupPREVIEW
    libraryLookup(Path path, SegmentScopePREVIEW scope)
    指定されたパス (まだロードされていない場合)からライブラリをロードし、そのライブラリ内のシンボルのシンボル・ルックアップを作成します。
    static SymbolLookupPREVIEW
    loaderLookup()
    呼び出し元クラス・ローダーに関連付けられたライブラリ内のシンボルのシンボル・ルックアップを返します。

  • メソッドの詳細

    • find

      Optional<MemorySegmentPREVIEW> find(String name)
      指定された名前のシンボルのアドレスを返します。
      パラメータ:
      name - シンボル名。
      戻り値:
      アドレスがシンボルのアドレスを示す長さがゼロのメモリー・セグメント(見つかった場合)。

    • loaderLookup

      static SymbolLookupPREVIEW loaderLookup()
      呼び出し元クラス・ローダーに関連付けられたライブラリ内のシンボルのシンボル・ルックアップを返します。

      ライブラリは、CLで定義されるクラスのコードからSystem.load(String)またはSystem.loadLibrary(String)を呼び出してライブラリをロードすると、クラス・ローダーCLに関連付けられます。 このコードによってSystem.load(String)またはSystem.loadLibrary(String)がさらに起動される場合、より多くのライブラリがロードされ、CLに関連付けられます。 このメソッドによって返されるシンボル・ルックアップは常に最新です: このメソッドが返された後にロードされた場合でも、関連するクラス・ローダーに関連付けられたすべてのライブラリが反映されます。

      クラス・ローダーに関連付けられたライブラリは、クラス・ローダーがunreachableになるとアンロードされます。 このメソッドから返されるシンボル検索は、常に有効であり、呼び出し元のクラス・ローダーが到達可能な範囲で支えられています。 したがって、コール元クラス・ローダーに関連付けられたライブラリは、そのクラス・ローダーに対するローダー・ルックアップがアクセス可能なかぎり、(およびそれらのシンボルが使用可能)をロードしたままになります。

      スタック(例、JNIアタッチ・スレッドから直接コールされる場合)にコール元フレームがないコンテキストからこのメソッドがコールされる場合、コール元クラス・ローダーはデフォルトで「システム・クラス・ローダー」に設定されます。

      戻り値:
      呼び出し元クラス・ローダーに関連付けられたライブラリ内のシンボルのシンボル・ルックアップ。
      関連項目:

    • libraryLookup

      static SymbolLookupPREVIEW libraryLookup(String name, SegmentScopePREVIEW scope)
      指定された名前 (まだロードされていない場合)のライブラリをロードし、そのライブラリ内のシンボルのシンボル・ルックアップを作成します。 指定されたスコープがalivePREVIEWではなくなると、ライブラリがアンロードされます(ほかのライブラリ検索でまだ使用されていない場合)。
      実装上のノート:
      ライブラリ名の解決プロセスはOS固有です。 たとえば、POSIX準拠のOSでは、ライブラリ名はそのOSのdlopen関数の指定に従って解決されます。 Windowsでは、ライブラリ名はLoadLibrary関数の指定に従って解決されます。

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

      パラメータ:
      name - シンボルを検索するライブラリの名前。
      scope - 返されるルックアップから取得されたシンボルに関連付けられたスコープ。
      戻り値:
      指定された名前を持つライブラリ内のシンボルを検索するのに適した新しいシンボル・ルックアップ。
      例外:
      IllegalArgumentException - nameが有効なライブラリを識別しない場合。
      IllegalCallerException - 呼び出し元が、ネイティブ・アクセスが有効になっていないモジュール内にある場合。

    • libraryLookup

      static SymbolLookupPREVIEW libraryLookup(Path path, SegmentScopePREVIEW scope)
      指定されたパス (まだロードされていない場合)からライブラリをロードし、そのライブラリ内のシンボルのシンボル・ルックアップを作成します。 指定されたスコープがalivePREVIEWではなくなると、ライブラリがアンロードされます(ほかのライブラリ検索でまだ使用されていない場合)。

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

      実装上のノート:
      Linuxでは、このファクトリ・メソッドによって提供される機能および返されるシンボル・ルックアップは、dlopen、dlsymおよびdlclose関数を使用して実装されます。
      パラメータ:
      path - シンボルを検索するライブラリのパス。
      scope - 返されるルックアップから取得されたシンボルに関連付けられたスコープ。
      戻り値:
      指定されたパスを持つライブラリ内のシンボルを見つけるのに適した新しいシンボル・ルックアップ。
      例外:
      IllegalArgumentException - pathが有効なライブラリを指していない場合。
      IllegalCallerException - 呼び出し元が、ネイティブ・アクセスが有効になっていないモジュール内にある場合。