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

インタフェースSymbolLookup

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

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

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

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

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

ファクトリ・メソッドlibraryLookup(String, Arena)およびlibraryLookup(Path, Arena)は、オペレーティング・システムで認識されているライブラリのシンボル・ルックアップを作成します。 ライブラリは、その名前またはパスで指定されます。 ライブラリがまだロードされていない場合はロードされます。 シンボルのルックアップは「ライブラリ・ルックアップ」と呼ばれ、その有効期間は「アリーナ」PREVIEWによって制御されます。 たとえば、指定されたアリーナが制限されたアリーナの場合、制限されたアリーナがclosedPREVIEWのとき、シンボル・ルックアップに関連付けられたライブラリはアンロードされます: 
 try (Arena arena = Arena.ofConfined()) {
     SymbolLookup libGL = SymbolLookup.libraryLookup("libGL.so", arena); // 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", arena).find("glGetString").isPresent(); // true
 loaderLookup().find("glGetString").isPresent(); // false
ライブラリLのライブラリ・ルックアップでは、Lが以前にJNI (クラス・ローダーとの関連付けはライブラリ・ルックアップにとって重要ではありません)を介してロードされている場合でも、Lのシンボルが公開されることにも注意してください: 
 System.loadLibrary("GL"); // libGL.so loaded here
 libraryLookup("libGL.so", arena).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, ArenaPREVIEW arena)
    指定された名前 (まだロードされていない場合)のライブラリをロードし、そのライブラリ内のシンボルのシンボル・ルックアップを作成します。
    static SymbolLookupPREVIEW
    libraryLookup(Path path, ArenaPREVIEW arena)
    指定されたパス (まだロードされていない場合)からライブラリをロードし、そのライブラリ内のシンボルのシンボル・ルックアップを作成します。
    static SymbolLookupPREVIEW
    loaderLookup()
    呼び出し元クラス・ローダーに関連付けられたライブラリ内のシンボルのシンボル・ルックアップを返します。
    default SymbolLookupPREVIEW
    or(SymbolLookupPREVIEW other)
    見つかった場合は、このルックアップでシンボルを検索した結果を返す合成記号ルックアップを返します。それ以外の場合は、別のルックアップでシンボルを検索した結果を返します。

  • メソッドの詳細

    • find

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

    • or

      default SymbolLookupPREVIEW or(SymbolLookupPREVIEW other)
      見つかった場合は、このルックアップでシンボルを検索した結果を返す合成記号ルックアップを返します。それ以外の場合は、別のルックアップでシンボルを検索した結果を返します。
      APIのノート:
      このメソッドは、複数のシンボル・ルックアップをまとめて連鎖するために使用できます。たとえば、シンボルを複数のライブラリから順番に取得できるようにするためです: 
       var lookup = SymbolLookup.libraryLookup("foo", arena)
         .or(SymbolLookup.libraryLookup("bar", arena))
         .or(SymbolLookup.loaderLookup());
      前述のコードは、最初に"foo"ライブラリ内のシンボルを検索するシンボル・ルックアップを作成します。 "foo"に記号が見つからない場合は、"バール"が検索されます。 最後に、"foo"と"バール"のどちらにもシンボルが見つからない場合は、「ローダー・ルックアップ」が使用されます。
      パラメータ:
      other - このルックアップで見つからないシンボルを検索するために使用すべきシンボル・ルックアップ。
      戻り値:
      見つかった場合は、このルックアップでシンボルを検索した結果を返す合成シンボル・ルックアップ。それ以外の場合は、ほかのルックアップでシンボルを検索した結果を返します

    • loaderLookup

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

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

      クラス・ローダーに関連付けられたライブラリは、クラス・ローダーがunreachableになるとアンロードされます。 このメソッドから返されるシンボル・ルックアップは、呼び出し元のクラス・ローダーが到達可能な状態を維持する新しいscopePREVIEWに関連付けられます。 そのため、コール元のクラス・ローダーに関連付けられたライブラリは、そのクラス・ローダーまたはそれによって取得されたセグメントのいずれかのローダー・ルックアップがアクセス可能なかぎり、ロードされた(およびそれらのシンボルが使用可能)が保持されます。

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

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

    • libraryLookup

      static SymbolLookupPREVIEW libraryLookup(String name, ArenaPREVIEW arena)
      指定された名前 (まだロードされていない場合)のライブラリをロードし、そのライブラリ内のシンボルのシンボル・ルックアップを作成します。 返されるライブラリ・ルックアップの存続期間は、指定されたアリーナによって制御されます。 たとえば、指定されたアリーナが限定されたアリーナの場合、指定された限定されたアリーナがclosedPREVIEWのときに、返されるルックアップに関連付けられたライブラリがアンロードされます。

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

      実装上のノート:
      ライブラリ名の解決プロセスはOS固有です。 たとえば、POSIX準拠のOSでは、ライブラリ名はそのOSのdlopen関数の指定に従って解決されます。 Windowsでは、ライブラリ名はLoadLibrary関数の指定に従って解決されます。
      パラメータ:
      name - シンボルを検索するライブラリの名前。
      arena - 返されるルックアップから取得されたシンボルに関連付けられたアリーナ。
      戻り値:
      指定された名前を持つライブラリ内のシンボルを検索するのに適した新しいシンボル・ルックアップ。
      例外:
      IllegalStateException - arena.scope().isAlive() == falseの場合
      WrongThreadException - arenaが限定されたアリーナで、このメソッドは、アリーナの所有者スレッド以外のスレッドTからコールされます。
      IllegalArgumentException - nameが有効なライブラリを識別しない場合。
      IllegalCallerException - 呼び出し元が、ネイティブ・アクセスが有効になっていないモジュール内にある場合。

    • libraryLookup

      static SymbolLookupPREVIEW libraryLookup(Path path, ArenaPREVIEW arena)
      指定されたパス (まだロードされていない場合)からライブラリをロードし、そのライブラリ内のシンボルのシンボル・ルックアップを作成します。 返されるライブラリ・ルックアップの存続期間は、指定されたアリーナによって制御されます。 たとえば、指定されたアリーナが限定されたアリーナの場合、指定された限定されたアリーナがclosedPREVIEWのときに、返されるルックアップに関連付けられたライブラリがアンロードされます。

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

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