weak

package standard library
go1.23.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 1, 2024 License: BSD-3-Clause Imports: 3 Imported by: 0

Documentation

Overview

The weak package is a package for managing weak pointers.

Weak pointers are pointers that explicitly do not keep a value live and must be queried for a regular Go pointer. The result of such a query may be observed as nil at any point after a weakly-pointed-to object becomes eligible for reclamation by the garbage collector. More specifically, weak pointers become nil as soon as the garbage collector identifies that the object is unreachable, before it is made reachable again by a finalizer. In terms of the C# language, these semantics are roughly equivalent to the the semantics of "short" weak references. In terms of the Java language, these semantics are roughly equivalent to the semantics of the WeakReference type.

Using go:linkname to access this package and the functions it references is explicitly forbidden by the toolchain because the semantics of this package have not gone through the proposal process. By exposing this functionality, we risk locking in the existing semantics due to Hyrum's Law.

If you believe you have a good use-case for weak references not already covered by the standard library, file a proposal issue at https://github.com/golang/go/issues instead of relying on this package.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Pointer

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

Pointer is a weak pointer to a value of type T.

This value is comparable is guaranteed to compare equal if the pointers that they were created from compare equal. This property is retained even after the object referenced by the pointer used to create a weak reference is reclaimed.

If multiple weak pointers are made to different offsets within same object (for example, pointers to different fields of the same struct), those pointers will not compare equal. If a weak pointer is created from an object that becomes reachable again due to a finalizer, that weak pointer will not compare equal with weak pointers created before it became unreachable.

func Make

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

Make creates a weak pointer from a strong pointer to some value of type T.

func (Pointer[T]) Strong

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

Strong creates a strong pointer from the weak pointer. Returns nil if the original value for the weak pointer was reclaimed by the garbage collector. If a weak pointer points to an object with a finalizer, then Strong will return nil as soon as the object's finalizer is queued for execution.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL