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

インタフェースMemoryAddress

すべてのスーパー・インタフェース:
Addressable
public sealed interface MemoryAddress extends Addressable
メモリー・アドレスは、メモリー・ロケーションへの参照をモデル化します。 通常、メモリー・アドレスはMemorySegment.address()メソッドを使用して取得され、off-heapまたはon-heapメモリーを参照できます。 オフ・ヒープ・メモリー・アドレスは、「ネイティブ」メモリー・アドレス(isNative()を参照してください)と呼ばれます。 ネイティブ・メモリー・アドレスを使用すると、クライアントはRAWメモリー・アドレス(long値で表す)を取得できます。これはネイティブ・コードとの対話時などに使用できます。

アドレスを指定すると、指定されたセグメントに対するオフセットをコンピュートできます。これは、メモリー・アクセスvarハンドル(MemoryHandlesを参照してください)を使用してメモリー間接参照演算を実行する場合に役立ちます。

メモリー・アドレスは「リソース・スコープ」に関連付けられます。リソース・スコープによって、メモリー・アドレスのライフサイクルと、複数のスレッドからアドレスを使用できるかどうかが決まります。 「数値」またはネイティブ・コードから取得されたメモリー・アドレスは、「グローバル・リソース・スコープ」に関連付けられます。 セグメントから取得されたメモリー・アドレスは、取得元のセグメントと同じスコープに関連付けられます。

このインタフェースのすべての実装はvalue-basedである必要があります。プログラマは、equalのインスタンスを交換可能として扱う必要があり、同期にインスタンスを使用しないでください。そうしないと、予期しない動作が発生する可能性があります。 たとえば、将来のリリースでは、同期が失敗する可能性があります。 比較する場合は、equalsメソッドを使用することをお薦めします。

非プラットフォーム・クラスは、MemoryAddressを直接実装することはできません。

特に指定がないかぎり、null引数、またはこのクラスのメソッドに1つ以上のnull要素を含む配列引数を渡すと、NullPointerExceptionがスローされます。

実装要件:
このインタフェースの実装は不変、スレッド・セーフ、およびvalue-basedです。

  • フィールドのサマリー

    フィールド
    修飾子と型
    フィールド
    説明
    static final MemoryAddress
    NULL
    ネイティブ・メモリー・アドレス・インスタンスは、「グローバル」リソース・スコープに関連付けられたNULLアドレスをモデリングします。

  • メソッドのサマリー

    修飾子と型
    メソッド
    説明
    MemoryAddress
    addOffset(long offset)
    指定されたオフセット(バイト単位)を使用して、現在のメモリー・アドレスから新しいメモリー・アドレスを生成します(負の場合もあります)。
    default MemoryAddress
    address()
    このオブジェクトをMemoryAddressインスタンスにマップします。
    MemorySegment
    asSegment(long bytesSize, Runnable cleanupAction, ResourceScope scope)
    指定されたサイズおよびリソース・スコープ(このアドレスにすでに関連付けられている範囲を置き換えます)を持つ新しいネイティブ・メモリー・セグメントを返し、そのベース・アドレスがこのアドレスです。
    MemorySegment
    asSegment(long bytesSize, ResourceScope scope)
    指定されたサイズおよびリソース・スコープ(このアドレスにすでに関連付けられている範囲を置き換えます)を持つ新しいネイティブ・メモリー・セグメントを返し、そのベース・アドレスがこのアドレスです。
    boolean
    equals(Object that)
    指定されたオブジェクトをこのアドレスと比較し、等価性を維持します。
    int
    hashCode()
    このアドレスのハッシュ・コード値を返します。
    boolean
    isNative()
    これはオフ・ヒープ・メモリー・アドレスですか。
    static MemoryAddress
    ofLong(long value)
    指定されたロング・アドレスからネイティブ・メモリー・アドレス・インスタンスを取得します。
    ResourceScope
    scope()
    このメモリー・アドレスに関連付けられたリソース・スコープを返します。
    long
    segmentOffset(MemorySegment segment)
    指定されたセグメントに対するこのメモリー・アドレスのオフセットを返します。
    long
    toRawLongValue()
    このネイティブ・メモリー・アドレスに関連付けられたraw long値を返します。

  • フィールド詳細

    • NULL

      static final MemoryAddress NULL
      ネイティブ・メモリー・アドレス・インスタンスは、「グローバル」リソース・スコープに関連付けられたNULLアドレスをモデリングします。

  • メソッドの詳細

    • address

      default MemoryAddress address()
      インタフェース: Addressableからコピーされた説明
      このオブジェクトをMemoryAddressインスタンスにマップします。
      定義:
      インタフェースAddressable内のaddress
      戻り値:
      このオブジェクトに関連付けられたMemoryAddressインスタンス。

    • addOffset

      MemoryAddress addOffset(long offset)
      指定されたオフセット(バイト単位)を使用して、現在のメモリー・アドレスから新しいメモリー・アドレスを生成します(負の場合もあります)。
      パラメータ:
      offset - 新しいアドレスの作成に使用する必要がある、このアドレスを基準とした相対位置のオフセット(バイト単位)を指定します。
      戻り値:
      現在のメモリー・アドレスからのオフセットが指定された新しいメモリー・アドレス。

    • scope

      ResourceScope scope()
      このメモリー・アドレスに関連付けられたリソース・スコープを返します。
      戻り値:
      このメモリー・アドレスに関連付けられたリソース・スコープ。

    • segmentOffset

      long segmentOffset(MemorySegment segment)
      指定されたセグメントに対するこのメモリー・アドレスのオフセットを返します。 具体的には、セグメント・ベース・アドレスとこのアドレスの両方がネイティブ・アドレスである場合、結果はthis.toRawLongValue() - segment.address().toRawLongValue()として計算されます。 Otherwise, if both addresses in the form (B, O1), (B, O2), where B is the same base heap object and O1, O2 are byte offsets (ベース・オブジェクトに対して相対的) associated with this address and the segment base address, the result is computed as O1 - O2.

      セグメントのベース・アドレスとこのアドレスの両方がヒープ・アドレスであるが、ベース・オブジェクトが異なる場合、結果は未定義となり、例外がスローされます。 同様に、セグメントのベース・アドレスがヒープ・アドレス(resp. off-heap)で、このアドレスがオフ・ヒープ(resp. heap)アドレスの場合、結果は未定義となり、例外がスローされます。 それ以外の場合、結果はバイト・オフセットSOになります。 このアドレスが特定のセグメントの空間境界内にある場合は0 <= SO < segment.byteSize()、それ以外の場合はSO < 0 || SO > segment.byteSize()。

      パラメータ:
      segment - このアドレス・オフセットが計算されるセグメント
      戻り値:
      指定されたセグメントへのこのメモリー・アドレスのオフセット。
      例外:
      IllegalArgumentException - segmentがこのアドレスと互換性がない場合。これは、たとえば、segmentがヒープ・メモリー・リージョンをモデル化し、このアドレスが「ネイティブ」アドレスの場合に発生します。

    • asSegment

      MemorySegment asSegment(long bytesSize, ResourceScope scope)
      指定されたサイズおよびリソース・スコープ(このアドレスにすでに関連付けられている範囲を置き換えます)を持つ新しいネイティブ・メモリー・セグメントを返し、そのベース・アドレスがこのアドレスです。 このメソッドは、カスタム・ネイティブ・メモリー・ソース(例:カスタム・ロケータ)と対話する場合に便利です。この場合、基礎となるメモリー・リージョンのアドレスは通常、ネイティブ・コード(プレーンlong値として使用されることが多い)から取得されます。 返されるセグメントは読取り専用(MemorySegment.isReadOnly()を参照してください)ではなく、指定されたリソース・スコープに関連付けられます。

      クライアントは、アドレスと境界が、読取りおよび書込みのためにアクセス可能なメモリーの有効なリージョンを参照していることを確認する必要があります。必要に応じて、Javaコードから無効なメモリーのロケーションにアクセスしようとすると、任意の値が返されるか、可視の効果がなくなるか、または未指定の例外がスローされます。

      このメソッドは次のコードと同等です。 

      
    asSegment(byteSize, null, scope);

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

      パラメータ:
      bytesSize - 目的のサイズ。
      scope - ネイティブ・セグメント・スコープ。
      戻り値:
      指定されたベース・アドレス、サイズ、およびスコープを持つ新しいネイティブ・メモリー・セグメント。
      例外:
      IllegalArgumentException - bytesSize <= 0の場合。
      IllegalStateException - このアドレスまたは指定されたスコープに関連付けられたスコープがすでにクローズされている場合、またはどちらか一方のスコープを所有するスレッド以外のスレッドからアクセスが発生した場合。
      UnsupportedOperationException - このアドレスが「ネイティブ」アドレスでない場合。
      IllegalCallerException - このメソッドへのアクセスがモジュールMから発生し、コマンドライン・オプション--enable-native-accessがない場合、またはモジュール名Mが名前なしモジュールの場合はALL-UNNAMEDは説明しません。

    • asSegment

      MemorySegment asSegment(long bytesSize, Runnable cleanupAction, ResourceScope scope)
      指定されたサイズおよびリソース・スコープ(このアドレスにすでに関連付けられている範囲を置き換えます)を持つ新しいネイティブ・メモリー・セグメントを返し、そのベース・アドレスがこのアドレスです。 このメソッドは、カスタム・ネイティブ・メモリー・ソース(例:カスタム・ロケータ)と対話する場合に便利です。この場合、基礎となるメモリー・リージョンのアドレスは通常、ネイティブ・コード(プレーンlong値として使用されることが多い)から取得されます。 返されるセグメントは、指定されたリソース・スコープに関連付けられます。

      クライアントは、アドレスと境界が、読取りおよび書込みのためにアクセス可能なメモリーの有効なリージョンを参照していることを確認する必要があります。必要に応じて、Javaコードから無効なメモリーのロケーションにアクセスしようとすると、任意の値が返されるか、可視の効果がなくなるか、または未指定の例外がスローされます。

      返されたセグメントに関連付けられたスコープでResourceScope.close()を呼び出すと、指定されたクリーンアップ・アクション(もしあれば)が呼び出されます。

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

      パラメータ:
      bytesSize - 目的のサイズ。
      cleanupAction - クリーンアップ・アクション。nullも指定できます。
      scope - ネイティブ・セグメント・スコープ。
      戻り値:
      指定されたベース・アドレス、サイズ、およびスコープを持つ新しいネイティブ・メモリー・セグメント。
      例外:
      IllegalArgumentException - bytesSize <= 0の場合。
      IllegalStateException - このアドレスまたは指定されたスコープに関連付けられたスコープがすでにクローズされている場合、またはどちらか一方のスコープを所有するスレッド以外のスレッドからアクセスが発生した場合。
      UnsupportedOperationException - このアドレスが「ネイティブ」アドレスでない場合。
      IllegalCallerException - このメソッドへのアクセスがモジュールMから発生し、コマンドライン・オプション--enable-native-accessがない場合、またはモジュール名Mが名前なしモジュールの場合はALL-UNNAMEDは説明しません。

    • isNative

      boolean isNative()
      これはオフ・ヒープ・メモリー・アドレスですか。
      戻り値:
      true。オフ・ヒープ・メモリー・アドレスの場合。

    • toRawLongValue

      long toRawLongValue()
      このネイティブ・メモリー・アドレスに関連付けられたraw long値を返します。
      戻り値:
      このネイティブ・メモリー・アドレスに関連付けられたraw long値。
      例外:
      UnsupportedOperationException - このメモリー・アドレスが「ネイティブ」アドレスでない場合。
      IllegalStateException - このセグメントに関連付けられたスコープがすでにクローズされている場合、またはいずれかのセグメントを所有するスレッド以外のスレッドからアクセスが発生した場合。

    • equals

      boolean equals(Object that)
      指定されたオブジェクトをこのアドレスと比較し、等価性を維持します。 指定されたオブジェクトもアドレスの場合のみ、trueを返し、このアドレスと同じメモリー・ロケーションを参照します。
      オーバーライド:
      equals、クラスObject
      APIのノート:
      関連するリソース・スコープが異なるにもかかわらず、2つのアドレスは等しいとみなされる可能性があります。 たとえば、同じメモリー・アドレスを使用して異なるスコープ(asSegment(long, ResourceScope)を使用して)を持つメモリー・セグメントを作成すると、結果のセグメントのベース・アドレスを比較できます。
      パラメータ:
      that - このアドレスと等価性を持たせるために比較するオブジェクト。
      戻り値:
      指定されたオブジェクトがこのアドレスと等しい場合、true。
      関連項目:

    • hashCode

      int hashCode()
      このアドレスのハッシュ・コード値を返します。
      オーバーライド:
      hashCode、クラスObject
      戻り値:
      このアドレスのハッシュ・コード値。
      関連項目:

    • ofLong

      static MemoryAddress ofLong(long value)
      指定されたロング・アドレスからネイティブ・メモリー・アドレス・インスタンスを取得します。 返されるアドレスは、「グローバル」リソース・スコープに関連付けられます。
      パラメータ:
      value - 長いアドレス。
      戻り値:
      新しいメモリー・アドレス・インスタンス。