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

インタフェースMemorySession

すべてのスーパー・インタフェース:
AutoCloseable, SegmentAllocatorPREVIEW
public sealed interface MemorySession extends AutoCloseable, SegmentAllocatorPREVIEW
MemorySessionは、JavaプラットフォームのプレビューAPIです。
プレビュー機能が有効な場合のみ、プログラムでMemorySessionを使用できます。
プレビュー機能は、今後のリリースで削除するか、Javaプラットフォームの永続機能にアップグレードすることができます。
メモリー・セッションは、1つ以上のリソースのライフサイクルを管理します。 メモリー・セッションに関連付けられたリソース(例、MemorySegmentPREVIEW)には、メモリー・セッションがaliveであり、メモリー・セッション(もしあれば)に関連付けられた「スレッド」によってのみアクセスできます。

メモリー・セッションはクローズできます。 メモリー・セッションが閉じられると、aliveではなくなり、そのセッション(例、MemorySegmentPREVIEWインスタンスにアクセスしようとしています)に関連付けられたリソースに対する後続の演算がIllegalStateExceptionで失敗します。

メモリー・セッションは、1つ以上の「アクションを閉じる」に関連付けられます。 クローズ・アクションを使用して、特定のリソース(またはリソースのセット)が使用されなくなった場合に実行する必要があるクリーンアップ・コードを指定できます。 メモリー・セッションが閉じられると、そのセッションに関連付けられた「アクションを閉じる」が(未指定の順序)に実行されます。 たとえば、1つ以上の「ネイティブ・メモリー・セグメント」PREVIEWに関連付けられたメモリー・セッションを閉じると、そのセグメントに関連付けられたオフ・ヒープ・メモリーが解放されます。

「グローバル・セッション」は、クローズできないメモリー・セッションです。 その結果、グローバル・セッションに関連付けられたリソースはリリースされません。 グローバル・メモリー・セッションに関連付けられたリソースの例は、「ヒープ・セグメント」PREVIEWです。

スレッド制限

メモリー・セッションは2つのカテゴリに分けることができます: 「スレッド制限」メモリー・セッションおよび「共有」メモリー・セッション。

制限付きメモリー・セッション、強いスレッド制限保証のサポート。 作成時に、「所有者スレッド」(通常は作成演算を開始したスレッド)が割り当てられます。 制限付きメモリー・セッションを作成したあと、所有者スレッドのみが、このメモリー・セッションに関連付けられたリソースを直接操作できます。 所有者スレッド以外のスレッドからリソース・アクセスを実行しようとすると、WrongThreadExceptionで失敗します。

一方、共有メモリー・セッションには所有者スレッドはありません。そのため、共有メモリー・セッションに関連付けられたリソースには複数のスレッドからアクセスできます。 これは、複数のスレッドが同じリソース (例:パラレル処理の場合)に同時にアクセスする必要がある場合に役立ちます。

クローズ可能なメモリー・セッション

セッションがオフ・ヒープ・リソースに関連付けられている場合、ガベージ・コレクタによってunreachableとみなされるセッションを待機するのではなく、そのようなリソースを適時にリリースすることが望ましい場合があります。 このシナリオでは、クライアントは「クローズ可能」メモリー・セッションの使用を検討します。 クローズ可能なメモリー・セッションは、次の例に示すように、決定的にclosedになる可能性があるメモリー・セッションです: 
try (MemorySession session = MemorySession.openConfined()) {
   MemorySegment segment1 = MemorySegment.allocateNative(100);
   MemorySegment segment1 = MemorySegment.allocateNative(200);
   ...
} // all memory released here
前述のコードは、限定されたクローズ可能なセッションを作成します。 次に、そのセッションに関連付けられた2つのセグメントが割り当てられます。 セッションがclosed (前述のとおり、これは「try-with-resourcesコンストラクト」を使用して暗黙的に実行されます)の場合、セッション内で割り当てられているすべてのメモリーが解放されます

クローズ可能なメモリー・セッションは強力ですが、注意して使用する必要があります。 クローズ可能なメモリー・セッションは、明示的に(close()メソッドをコール)または暗黙的に(「try-with-resourcesコンストラクト」でクローズ可能なメモリー・セッションの使用をラップ)のいずれかが使用されなくなったときにクローズする必要があります。 そうしないと、メモリー・リークが発生する可能性があります。 この問題を軽減するために、クローズ可能なメモリー・セッションをCleanerインスタンスに関連付けて、セッション・インスタンスがunreachableになったら自動的にクローズされるようにできます。 これは、偶発的なネイティブ・メモリー・リークを防止しながら、予測可能な確定的リソース・ロケーションを許可するのに役立ちます。 クリーナによって管理されるメモリー・セッションをクライアントがクローズした場合、セッションが到達不可能になったとき、これ以上のアクションは実行されません。つまり、メモリー・セッションに関連付けられた「アクションを閉じる」は、管理対象かどうかに関係なく、「1回のみ」と呼ばれます。

非クローズ可能なビュー

メモリー・セッションが関連付けられている1つ以上のリソースからアクセス可能になることが望ましくない場合があります。 たとえば、APIではプライベート・メモリー・セッションを作成し、メモリー・セグメントを割り当て、このセグメントの1つ以上のスライスをクライアントに公開できます。 APIメモリー・セッションはスライス(MemorySegment.session()PREVIEWアクセサの使用)から到達可能であるため、クライアントがAPI (例、セッションを途中で閉じます)を危険にさらす可能性があります。 プライベート・メモリー・セッションが信頼できないクライアントに漏れないように、APIでは、次のように、作成したセッションのクローズ不可ビューに基づいてセグメントを戻すことができます: 
MemorySession session = MemorySession.openConfined();
MemorySession nonCloseableSession = session.asNonCloseable();
MemorySegment segment = MemorySegment.allocateNative(100, nonCloseableSession);
segment.session().close(); // throws
session.close(); //ok
つまり、元のsessionオブジェクトの所有者のみがセッションをクローズできます。 外部クライアントはクローズ不可セッションにのみアクセスでき、基礎となるAPIセッションにはアクセスできません。
実装要件:
このインタフェースの実装はスレッド・セーフです。
導入されたバージョン:
19
関連項目:

  • メソッドの詳細

    • isAlive

      boolean isAlive()
      このメモリー・セッションが有効な場合は、trueを返します。
      戻り値:
      true。このメモリー・セッションが有効である場合

    • isCloseable

      boolean isCloseable()
      このセッションがクローズ可能なメモリー・セッションである場合は、trueを返します。
      戻り値:
      true(このセッションがクローズ可能なメモリー・セッションの場合)

    • ownerThread

      Thread ownerThread()
      このメモリー・セッションに関連付けられた所有者スレッドを返します。このセッションが複数のスレッドで共有されている場合はnullを返します。
      戻り値:
      このメモリー・セッションに関連付けられた所有者スレッド、またはこのセッションが複数のスレッドで共有されている場合はnull

    • whileAlive

      void whileAlive(Runnable action)
      このメモリー・セッションが存続している間に重要なアクションを実行します。
      パラメータ:
      action - 実行するアクション。

    • addCloseAction

      void addCloseAction(Runnable runnable)
      メモリー・セッションが閉じられるときに実行されるカスタム・クリーン・アップ・アクションを追加します。 メモリー・セッションが閉じられるとカスタム・クリーン・アップ・アクションが呼び出される順序は不確定です。
      APIのノート:
      指定されたアクションでは、暗黙的に閉じられたセッションをCleanerインスタンスで正しく処理できるように、このメモリー・セッションへの強力な参照を保持しないでください。
      パラメータ:
      runnable - このメモリー・セッションに関連付けるカスタム・クリーン・アップ・アクション。
      例外:
      IllegalStateException - このメモリー・セッションがaliveでない場合。
      WrongThreadException - このメソッドが、このメモリー・セッションを「所有している」スレッド以外から呼び出された場合。

    • close

      void close()
      このメモリー・セッションを閉じます。 この演算が例外なしで完了すると、このセッションは「生きていない」としてマークされ、このセッションに関連付けられた「アクションを閉じる」が実行され、このセッションに関連付けられたすべてのリソースが解放されます。
      定義:
      close、インタフェースAutoCloseable
      APIのノート:
      この演算はべき等ではありません。つまり、すでに閉じたメモリー・セッションalwaysを閉じると、例外がスローされます。 これは意図的な設計の選択を反映しています: メモリー・セッションの状態遷移はクライアント・コード内でマニフェスト化する必要があります。これらの遷移のいずれかに失敗すると、基礎となるアプリケーション・ロジックのバグが明らかになります。
      例外:
      IllegalStateException - このメモリー・セッションがaliveでない場合。
      IllegalStateException - このセッションが別のクライアントによって「キープ・アライブ」である場合。
      WrongThreadException - このメソッドが、このメモリー・セッションを「所有している」スレッド以外から呼び出された場合。
      UnsupportedOperationException - このメモリー・セッションが「クローズ可能」でない場合。
      関連項目:

    • asNonCloseable

      MemorySessionPREVIEW asNonCloseable()
      このメモリー・セッションを閉じられないビューを返します。 このセッションがnon-closeableの場合、このセッションが返されます。 それ以外の場合、このメソッドは、このメモリー・セッションを閉じられないビューを返します。
      APIのノート:
      メモリー・セッションSのクローズ不可能なビューは、Sにアクセス可能なままにします。 したがって、Sの1つ以上のクローズ不可能なビューに到達できるかぎり、Sを暗黙的に(例、Cleanerにより)にクローズすることはできません。
      戻り値:
      このメモリー・セッションを閉じられないビュー。

    • equals

      boolean equals(Object that)
      指定されたオブジェクトをこのメモリー・セッションと比較し、等しいかどうかを調べます。 指定されたオブジェクトがメモリー・セッションでもあり、このメモリー・セッションと同じメモリー・セッションを参照する場合のみ、trueを返します。 メモリー・セッションSの「非クローズ可能なビュー」 Vは、Sと等しいとみなされます。
      オーバーライド:
      equals、クラスObject
      パラメータ:
      that - このメモリー・セッションとの等価性を比較するオブジェクト。
      戻り値:
      指定したオブジェクトがこのメモリー・セッションと等しい場合はtrue。
      関連項目:

    • hashCode

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

    • allocate

      default MemorySegmentPREVIEW allocate(long bytesSize, long bytesAlignment)
      このセッションを使用してネイティブ・セグメントを割り当てます。 次のコードと同等です: 
      MemorySegment.allocateNative(size, align, this);
      定義:
      インタフェースSegmentAllocatorPREVIEW内のallocate
      パラメータ:
      bytesSize - 割り当てるメモリー・ブロックのサイズ(バイト単位)。
      bytesAlignment - 割り当てるメモリー・ブロックの整列(バイト単位)。
      戻り値:
      このセッションに関連付けられた新しいネイティブ・セグメント。
      例外:
      IllegalStateException - このメモリー・セッションがaliveでない場合。
      WrongThreadException - このメソッドが、このメモリー・セッションを「所有している」スレッド以外から呼び出された場合。

    • openConfined

      static MemorySessionPREVIEW openConfined()
      閉じた制限付きメモリー・セッションを作成します。
      戻り値:
      新しい閉じた制限付きメモリー・セッション。

    • openConfined

      static MemorySessionPREVIEW openConfined(Cleaner cleaner)
      指定されたクリーナ・インスタンスによって管理されるクローズ可能な制限付きメモリー・セッションを作成します。
      パラメータ:
      cleaner - 返されたメモリー・セッションに関連付けるクリーナ。
      戻り値:
      cleanerによって管理される新しいクローズ可能な制限付きメモリー・セッション。

    • openShared

      static MemorySessionPREVIEW openShared()
      クローズ可能な共有メモリー・セッションを作成します。
      戻り値:
      新しいクローズ可能な共有メモリー・セッション。

    • openShared

      static MemorySessionPREVIEW openShared(Cleaner cleaner)
      指定されたクリーナ・インスタンスによって管理されるクローズ可能な共有メモリー・セッションを作成します。
      パラメータ:
      cleaner - 返されたメモリー・セッションに関連付けるクリーナ。
      戻り値:
      cleanerによって管理される新しいクローズ可能な共有メモリー・セッション。

    • openImplicit

      static MemorySessionPREVIEW openImplicit()
      プライベートCleanerインスタンスによって管理されるクローズ不可の共有メモリー・セッションを作成します。 (ただし、より効率的である可能性があります。)と同等のコードは次のとおりです: 
      openShared(Cleaner.create()).asNonCloseable();
      戻り値:
      プライベートCleanerインスタンスによって管理される、クローズ不可能な共有メモリー・セッション。

    • global

      static MemorySessionPREVIEW global()
      グローバル・メモリー・セッションを返します。
      戻り値:
      グローバル・メモリー・セッション。