package arena

Import Path
	arena (on go.dev)

Dependency Relation
	imports 2 packages, and imported by one package


Involved Source Files

	
		The arena package provides the ability to allocate memory for a collection
		of Go values and free that space manually all at once, safely. The purpose
		of this functionality is to improve efficiency: manually freeing memory
		before a garbage collection delays that cycle. Less frequent cycles means
		the CPU cost of the garbage collector is incurred less frequently.
		
		This functionality in this package is mostly captured in the Arena type.
		Arenas allocate large chunks of memory for Go values, so they're likely to
		be inefficient for allocating only small amounts of small Go values. They're
		best used in bulk, on the order of MiB of memory allocated on each use.
		
		Note that by allowing for this limited form of manual memory allocation
		that use-after-free bugs are possible with regular Go values. This package
		limits the impact of these use-after-free bugs by preventing reuse of freed
		memory regions until the garbage collector is able to determine that it is
		safe. Typically, a use-after-free bug will result in a fault and a helpful
		error message, but this package reserves the right to not force a fault on
		freed memory. That means a valid implementation of this package is to just
		allocate all memory the way the runtime normally would, and in fact, it
		reserves the right to occasionally do so for some Go values.


Package-Level Type Names (only one)


	/* sort by:  |  */
	
		Arena represents a collection of Go values allocated and freed together.
		Arenas are useful for improving efficiency as they may be freed back to
		the runtime manually, though any memory obtained from freed arenas must
		not be accessed once that happens. An Arena is automatically freed once
		it is no longer referenced, so it must be kept alive (see runtime.KeepAlive)
		until any memory allocated from it is no longer needed.
		
		An Arena must never be used concurrently by multiple goroutines.

		
			
				Free frees the arena (and all objects allocated from the arena) so that
				memory backing the arena can be reused fairly quickly without garbage
				collection overhead. Applications must not call any method on this
				arena after it has been freed.

		
			func NewArena() *Arena
		
			func MakeSlice[T](a *Arena, len, cap int) []T
			func New[T](a *Arena) *T
			func reflect.ArenaNew(a *Arena, typ reflect.Type) reflect.Value




Package-Level Functions (total 4)


	

		Type Parameters:
			T: any

		Clone makes a shallow copy of the input value that is no longer bound to any
		arena it may have been allocated from, returning the copy. If it was not
		allocated from an arena, it is returned untouched. This function is useful
		to more easily let an arena-allocated value out-live its arena.
		T must be a pointer, a slice, or a string, otherwise this function will panic.


	

		Type Parameters:
			T: any

		MakeSlice creates a new []T with the provided capacity and length. The []T must
		not be used after the arena is freed. Accessing the underlying storage of the
		slice after free may result in a fault, but this fault is also not guaranteed.


	

		Type Parameters:
			T: any

		New creates a new *T in the provided arena. The *T must not be used after
		the arena is freed. Accessing the value after free may result in a fault,
		but this fault is also not guaranteed.


	
		NewArena allocates a new arena.