pointers

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.

 	Ask(ptr) (ptr T, pinned bool, letted bool)
	AsA[T](ptr) T // unsafe conversion between different pointer types of the same size.

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.