weak

Documentation

Overview

Package weak は、メモリをガベージコレクションの対象から除外することなく、 安全に弱い参照を行う方法を提供します。

Index

• type Pointer
  • func Make[T any](ptr *T) Pointer[T]
  • func (p Pointer[T]) Value() *T

Types

type Pointer

type Pointer[T any] struct {
	// contains filtered or unexported fields
}

Pointer は型 T の値への弱いポインタです。

通常のポインタと同様に、Pointer はオブジェクトの任意の部分 （例えば構造体のフィールドや配列の要素）を参照できます。 弱いポインタのみで参照されているオブジェクトは到達可能とはみなされず、 オブジェクトが到達不可能になると、Pointer.Value は nil を返す場合があります。

弱いポインタの主な用途は、キャッシュの実装、正規化マップ（unique パッケージなど）、 および別々の値のライフタイムを結びつけること（例えば弱いキーを持つマップを通じて）です。

2 つの Pointer 値は、それらが作成された元のポインタが等しい場合に限り等しくなります。 この性質は、弱い参照を作成するために使用したポインタが参照するオブジェクトが 回収された後も維持されます。 同じオブジェクト内の異なるオフセット（例えば同じ構造体の異なるフィールドへのポインタ） に対して複数の弱いポインタが作成された場合、それらのポインタは等しくなりません。 つまり、弱いポインタは単純なアドレスではなく、オブジェクトとそのオブジェクト内の オフセットに対応します。 弱いポインタが到達不可能になったオブジェクトから作成された場合でも、 ファイナライザにより復活した場合、その弱いポインタは復活後に作成された 弱いポインタと等しくなりません。

nil ポインタを渡して Make を呼び出すと、Pointer.Value が常に nil を返す 弱いポインタが返されます。Pointer のゼロ値は、nil を Make に渡して作成された かのように振る舞い、そのようなポインタと等しくなります。

Pointer.Value が最終的に nil を返すことは保証されていません。 Pointer.Value はオブジェクトが到達不可能になるとすぐに nil を返す場合があります。 グローバル変数に格納された値、またはグローバル変数からポインタをたどって見つけられる値は 到達可能です。関数の引数やレシーバは、関数がそれを最後に参照した時点で 到達不可能になる場合があります。Pointer.Value が nil を返さないようにするには、 オブジェクトが到達可能でなければならない最後の時点の後で、 オブジェクトへのポインタを runtime.KeepAlive 関数に渡してください。

Pointer.Value が最終的に nil を返すことが保証されていないため、 オブジェクトが参照されなくなった後でも、ランタイムは複数のオブジェクトを 1 つのアロケーションスロットにまとめる省スペース最適化を行うことが許可されています。 そのようなアロケーション内で参照されていないオブジェクトの弱いポインタは、 参照されているオブジェクトと常に同じバッチに存在する場合、nil にならないことがあります。 通常、このバッチ処理は小さな（16 バイト以下程度）かつポインタを持たないオブジェクトに 対してのみ発生します。

func Make

func Make[T any](ptr *T) Pointer[T]

Make は型 T の値へのポインタから弱いポインタを作成します。

func (Pointer[T]) Value

func (p Pointer[T]) Value() *T

Value は弱いポインタを作成するために使用した元のポインタを返します。 元のポインタが指していた値がガベージコレクタによって回収された場合は nil を返します。 弱いポインタがファイナライザを持つオブジェクトを指している場合、 オブジェクトのファイナライザが実行キューに入れられるとすぐに Value は nil を返します。