pointers

Documentation

Overview

Package pointers provides managed pointers that are invisible to the Go runtime.

Usually, the Go runtime attempts to scan all pointers within a program and as such, the more pointers in use, the more overhead there will be to scan them.

When working with fixed pointers allocated outside of the runtime, the naive approach would be to use a uintptr instead of a typed pointer but this can easily lead right into unsafe and undefined behavior as well as memory leaks. runtime.SetFinalizer is another option, except, this requires additional allocations and overhead that makes it unsuitable for scenarios where thousands of pointers are in use.

Pointers exclusively managed through this package are protected against double frees, use-after-free and leaks. Runtime panics will be raised if any unsafe use is detected.

The following constructors are available:

New(ptr) // panics-on-use after two garbage collection cycles.
Let(ptr) // like [New], but [End] operations on this pointer always return false.
Raw(ptr) // unsafe.Pointer equivalent, zero overhead, but provides no protection.
Add(ptr) // allocates and returns a static pointer that can be mutated with Set.

The following methods are available:

Set(X, ptr) // sets and returns the mutable pointer at slot N.
End(X) (ptr, bool) // returns true on the first call to [End], false on all subsequent calls, GC-related metadata is marked for reuse.
Use(ptr) // refreshes a [New] pointer, as if it were just allocated, similar (in some sense) to [runtime.KeepAlive].
Pin(ptr) // pin a [New] pointer, so that it will be available for use until the next call to [Free]
Bad(ptr) // returns true if the pointer is nil, or freed.
Lay(ptr) // converts a [New] pointer to a [Let] pointer.

Cycle should be called periodically to invalidate any pointer-related resources for re-use. Invalidated pointers will eventually have their [Free] method called as long as the program continues to construct new pointers of the same types.

The [For] function returns an iterator for all pointers of a given type, this can be used to free all pointers of a given type. Up to 16 pointer types for each shape are currently supported.

Index

• func Add[T Generic[T, P], P Size](val P) T
• func Bad[T Generic[T, P], P Size](ptr T) bool
• func Cycle()
• func Debug[T Generic[T, P], P Size](ptr T)
• func End[T Generic[T, Raw], Raw Size](ptr T) (Raw, bool)
• func Get[T Generic[T, P], P Size](ptr T) P
• func Lay[T Generic[T, P], P Size](ptr T) T
• func Let[T Generic[T, P], P Size](ptr P) T
• func Load[T Generic[T, P], P Size](data complex128) T
• func New[T Generic[T, P], P Size](ptr P) T
• func Pack[T Generic[T, P], P Size](ptr T) complex128
• func Pin[T Generic[T, P], P Size](ptr T) T
• func Raw[T Generic[T, P], P Size](ptr P) T
• func Set[T Generic[T, P], P Size](ptr T, val P)
• type Generic
• type Half
• type Pair
• type Size
• type Solo
• type Trio

Functions

func Add

func Add[T Generic[T, P], P Size](val P) T

Add allocates a new pointer that can be mutated with Set.

func Bad

func Bad[T Generic[T, P], P Size](ptr T) bool

Bad returns true if the pointer is nil, or freed.

func Cycle

func Cycle()

Cycle triggers an deadline garbage collection cycle, to clean up temporary objects, only pointers allocated in the current or last cycle will be preserved.

func Debug

func Debug[T Generic[T, P], P Size](ptr T)

Debug prints the current state of the pointer.

func End

func End[T Generic[T, Raw], Raw Size](ptr T) (Raw, bool)

End the lifetime of the pointer, returning the underlying pointer value and ok=true if this is the first time the pointer has been freed.

func Get

func Get[T Generic[T, P], P Size](ptr T) P

Get returns the underlying pointer value, or panics if the pointer has been freed.

func Lay

func Lay[T Generic[T, P], P Size](ptr T) T

Lay the pointer, preventing the free operation from being called on it (it can still expire).

func Let

func Let[T Generic[T, P], P Size](ptr P) T

Let returns a borrowed pointer, which we will not be freed when End is called.

func Load

func Load[T Generic[T, P], P Size](data complex128) T

func New

func New[T Generic[T, P], P Size](ptr P) T

New manages the given pointer value discretely.

func Pack

func Pack[T Generic[T, P], P Size](ptr T) complex128

func Pin

func Pin[T Generic[T, P], P Size](ptr T) T

Pin the pointer, preventing it from being freed until [Free] is called on it.

func Raw

func Raw[T Generic[T, P], P Size](ptr P) T

Raw returns an unsafe.Pointer equivalent to [Pointer], zero overhead, but it provides no protections on use.

func Set

func Set[T Generic[T, P], P Size](ptr T, val P)

Set overwrites the underlying added pointer value.

Types

type Generic

type Generic[T any, S Size] interface {
	~struct {
		// contains filtered or unexported fields
	}
	Free()
}

Generic pointer.

type Half

type Half[T Generic[T, [1]uint32]] struct {
	// contains filtered or unexported fields
}

Half pointer value that safely wraps a single uintptr-sized value.

type Pair

type Pair[T Generic[T, [2]uint64]] struct {
	// contains filtered or unexported fields
}

Pair pointer value that safely wraps a pair of uintptr-sized values.

type Size

type Size interface {
	[1]uint32 | [1]uint64 | [2]uint64 | [3]uint64
}

Size of a pointer up to [3]uintptr's, suitable for supporting fat pointers.

type Solo

type Solo[T Generic[T, [1]uint64]] struct {
	// contains filtered or unexported fields
}

Solo pointer value that safely wraps a single uintptr-sized value.

type Trio

type Trio[T Generic[T, [3]uint64]] struct {
	// contains filtered or unexported fields
}

Trio pointer value that safely wraps three uintptr-sized values.