memory

package
v0.212.0 Latest Latest
Warning

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

 Go to latest Published: Aug 12, 2026 License: MIT Imports: 6 Imported by: 0

README

Go+ region memory

memory is the backend-neutral runtime foundation for explicit bulk lifetime management. Native builds reserve storage outside the traced Go heap; WASM and Plan 9 use reusable linear/managed storage.

The first release deliberately exposes generation-checked byte handles rather than pointers. A retained byte slice cannot outlive an arena because reads and writes copy through the handle. Delete, Rollback, and Reset invalidate handles immediately. Secure zeroing is the default.

An omitted Config.Zero selects ZeroOnRelease; an omitted Config.Storage selects PlatformStorage. Alignment arithmetic is capacity-bounded, so even host-sized alignments fail with CapacityExhausted rather than wrapping.

Future Go+ compiler releases will layer lexical lifetime indices, linear owned values, borrowed references, stack-placement proofs, and //goplus:layout soa over this representation.

Allocation groups

Arena.Group creates an explicit ownership boundary over related allocations. Group.Reset securely releases every member while keeping the group reusable; Group.Release permanently closes the capability. Handles released by either operation remain invalid even when their spans are reused.

Structure-of-arrays layouts

SoA2 and SoA3 provide typed columnar storage and deterministic conversion from and back to Row2 and Row3 AoS values. Reset clears logical contents while retaining capacity for hot-path reuse; Release clears and drops the backing columns.

Reusable typed buffers

Buffer[T] provides capacity-preserving reset for pointer-bearing runtime state. Indexed removal clears the vacated slot before shortening the slice so discarded objects stop being GC roots. Release clears all elements and drops the backing allocation as one ownership group.

Documentation

Overview

Package memory provides explicit region lifetime, ownership, clearing, and reuse. Its primary Go+ API is algebraic: expected failures travel on Result, optional free-span locations travel on Option, and policy/state alternatives are exhaustive enums.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Error 

func Error(failure Failure) string

func FailureEqual 

func FailureEqual(a, b Failure) bool

FailureEqual reports structural equality of a and b.

func FailureEqualWith 

func FailureEqualWith(a, b Failure, ov FailureEqOverrides) bool

FailureEqualWith reports structural equality of a and b under ov.

func FailureFold 

func FailureFold[R any](f Failure, cs FailureCases[R]) R

FailureFold reduces Failure by one-level case analysis.

func MutationEqual 

func MutationEqual(a, b Mutation) bool

MutationEqual reports structural equality of a and b.

func MutationEqualWith 

func MutationEqualWith(a, b Mutation, ov MutationEqOverrides) bool

MutationEqualWith reports structural equality of a and b under ov.

func MutationFold 

func MutationFold[R any](m Mutation, cs MutationCases[R]) R

MutationFold reduces Mutation by one-level case analysis.

func New 

func New(config Config) result.Result[*Arena, Failure]

func StoragePolicyEqual added in v0.211.0 

func StoragePolicyEqual(a, b StoragePolicy) bool

StoragePolicyEqual reports structural equality of a and b.

func StoragePolicyEqualWith added in v0.211.0 

func StoragePolicyEqualWith(a, b StoragePolicy, ov StoragePolicyEqOverrides) bool

StoragePolicyEqualWith reports structural equality of a and b under ov.

func StoragePolicyFold added in v0.211.0 

func StoragePolicyFold[R any](s StoragePolicy, cs StoragePolicyCases[R]) R

StoragePolicyFold reduces StoragePolicy by one-level case analysis.

func Unwrap 

func Unwrap(failure Failure) error

func ZeroPolicyEqual 

func ZeroPolicyEqual(a, b ZeroPolicy) bool

ZeroPolicyEqual reports structural equality of a and b.

func ZeroPolicyEqualWith 

func ZeroPolicyEqualWith(a, b ZeroPolicy, ov ZeroPolicyEqOverrides) bool

ZeroPolicyEqualWith reports structural equality of a and b under ov.

func ZeroPolicyFold 

func ZeroPolicyFold[R any](z ZeroPolicy, cs ZeroPolicyCases[R]) R

ZeroPolicyFold reduces ZeroPolicy by one-level case analysis.

Types

type Applied 

type Applied struct{}

type Arena 

type Arena struct {
	// contains filtered or unexported fields
}

func (*Arena) Allocate 

func (arena *Arena) Allocate(size int, alignment int) result.Result[Handle, Failure]

func (*Arena) Bytes 

func (arena *Arena) Bytes(handle Handle) result.Result[[]byte, Failure]

func (*Arena) Checkpoint 

func (arena *Arena) Checkpoint() result.Result[Checkpoint, Failure]

func (*Arena) Close 

func (arena *Arena) Close() result.Result[Mutation, Failure]

func (*Arena) Delete 

func (arena *Arena) Delete(handle Handle) result.Result[Mutation, Failure]

func (*Arena) Group 

func (arena *Arena) Group() result.Result[*Group, Failure]

func (*Arena) Read 

func (arena *Arena) Read(handle Handle, at int, destination []byte) result.Result[Mutation, Failure]

func (*Arena) Reset 

func (arena *Arena) Reset() result.Result[Mutation, Failure]

func (*Arena) Rollback 

func (arena *Arena) Rollback(checkpoint Checkpoint) result.Result[Mutation, Failure]

func (*Arena) Stats 

func (arena *Arena) Stats() Stats

func (*Arena) Write 

func (arena *Arena) Write(handle Handle, at int, source []byte) result.Result[Mutation, Failure]

func (*Arena) Zero 

func (arena *Arena) Zero(handle Handle) result.Result[Mutation, Failure]

type ArenaClosed 

type ArenaClosed struct{}

type BoundsViolation 

type BoundsViolation struct {
	Operation string
}

type Buffer 

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

func NewBuffer 

func NewBuffer[T any](capacity int) Buffer[T]

func (*Buffer[T]) Append 

func (buffer *Buffer[T]) Append(value T)

func (Buffer[T]) At 

func (buffer Buffer[T]) At(index int) option.Option[T]

func (Buffer[T]) Cap 

func (buffer Buffer[T]) Cap() int

func (Buffer[T]) Len 

func (buffer Buffer[T]) Len() int

func (*Buffer[T]) Release 

func (buffer *Buffer[T]) Release()

func (*Buffer[T]) Remove 

func (buffer *Buffer[T]) Remove(index int) option.Option[T]

func (*Buffer[T]) Reset 

func (buffer *Buffer[T]) Reset()

func (*Buffer[T]) Set 

func (buffer *Buffer[T]) Set(index int, value T) bool

func (*Buffer[T]) Truncate 

func (buffer *Buffer[T]) Truncate(length int) bool

type CapacityExhausted 

type CapacityExhausted struct{}

type Checkpoint 

type Checkpoint struct {
	// contains filtered or unexported fields
}

type Config 

type Config struct {
	Capacity int
	Zero     ZeroPolicy
	Storage  StoragePolicy
}

type Failure 

type Failure interface {
	// contains filtered or unexported methods
}

type FailureCases 

type FailureCases[R any] struct {
	ArenaClosed          func() R
	CapacityExhausted    func() R
	InvalidHandle        func() R
	InvalidCheckpoint    func() R
	InvalidConfiguration func(Message string) R
	BoundsViolation      func(Operation string) R
	PlatformFailure      func(Cause error) R
	GroupReleased        func() R
}

FailureCases selects one handler per Failure variant for FailureFold.

type FailureEqOverrides 

type FailureEqOverrides struct {
	ArenaClosed          func(x, y ArenaClosed) (eq, handled bool)
	CapacityExhausted    func(x, y CapacityExhausted) (eq, handled bool)
	InvalidHandle        func(x, y InvalidHandle) (eq, handled bool)
	InvalidCheckpoint    func(x, y InvalidCheckpoint) (eq, handled bool)
	InvalidConfiguration func(x, y InvalidConfiguration) (eq, handled bool)
	BoundsViolation      func(x, y BoundsViolation) (eq, handled bool)
	PlatformFailure      func(x, y PlatformFailure) (eq, handled bool)
	GroupReleased        func(x, y GroupReleased) (eq, handled bool)
}

FailureEqOverrides carries optional per-variant hooks for FailureEqualWith. A hook returning handled=false falls through to the derived comparison.

type Group 

type Group struct {
	// contains filtered or unexported fields
}

func (*Group) Allocate 

func (group *Group) Allocate(size int, alignment int) result.Result[Handle, Failure]

func (*Group) Release 

func (group *Group) Release() result.Result[Mutation, Failure]

func (*Group) Reset 

func (group *Group) Reset() result.Result[Mutation, Failure]

func (*Group) Stats 

func (group *Group) Stats() (Allocations int, Released bool)

type GroupReleased 

type GroupReleased struct{}

type Handle 

type Handle struct {
	// contains filtered or unexported fields
}

func (Handle) IsZero 

func (handle Handle) IsZero() bool

func (Handle) Len 

func (handle Handle) Len() int

type InvalidCheckpoint 

type InvalidCheckpoint struct{}

type InvalidConfiguration 

type InvalidConfiguration struct {
	Message string
}

type InvalidHandle 

type InvalidHandle struct{}

type ManagedStorage added in v0.211.0 

type ManagedStorage struct{}

type Mutation 

type Mutation interface {
	// contains filtered or unexported methods
}

type MutationCases 

type MutationCases[R any] struct {
	Applied func() R
}

MutationCases selects one handler per Mutation variant for MutationFold.

type MutationEqOverrides 

type MutationEqOverrides struct {
	Applied func(x, y Applied) (eq, handled bool)
}

MutationEqOverrides carries optional per-variant hooks for MutationEqualWith. A hook returning handled=false falls through to the derived comparison.

type PlatformFailure 

type PlatformFailure struct {
	Cause error
}

type PlatformStorage added in v0.211.0 

type PlatformStorage struct{}

type PreserveOnRelease 

type PreserveOnRelease struct{}

PreserveOnRelease is an explicit performance capability. Its caller must prove released bytes are neither secret nor observable before overwrite.

type Row2 

type Row2[A, B any] struct {
	First  A
	Second B
}

type Row3 

type Row3[A, B, C any] struct {
	First  A
	Second B
	Third  C
}

type SoA2 

type SoA2[A, B any] struct {
	// contains filtered or unexported fields
}

func FromRows2 

func FromRows2[A, B any](rows []Row2[A, B]) SoA2[A, B]

func NewSoA2 

func NewSoA2[A, B any](capacity int) SoA2[A, B]

func (*SoA2[A, B]) Append 

func (columns *SoA2[A, B]) Append(first A, second B)

func (SoA2[A, B]) At 

func (columns SoA2[A, B]) At(index int) option.Option[Row2[A, B]]

func (SoA2[A, B]) Len 

func (columns SoA2[A, B]) Len() int

func (*SoA2[A, B]) Release 

func (columns *SoA2[A, B]) Release()

func (*SoA2[A, B]) Reset 

func (columns *SoA2[A, B]) Reset()

func (SoA2[A, B]) Rows 

func (columns SoA2[A, B]) Rows() []Row2[A, B]

type SoA3 

type SoA3[A, B, C any] struct {
	// contains filtered or unexported fields
}

func FromRows3 

func FromRows3[A, B, C any](rows []Row3[A, B, C]) SoA3[A, B, C]

func NewSoA3 

func NewSoA3[A, B, C any](capacity int) SoA3[A, B, C]

func (*SoA3[A, B, C]) Append 

func (columns *SoA3[A, B, C]) Append(first A, second B, third C)

func (SoA3[A, B, C]) At 

func (columns SoA3[A, B, C]) At(index int) option.Option[Row3[A, B, C]]

func (SoA3[A, B, C]) Len 

func (columns SoA3[A, B, C]) Len() int

func (*SoA3[A, B, C]) Release 

func (columns *SoA3[A, B, C]) Release()

func (*SoA3[A, B, C]) Reset 

func (columns *SoA3[A, B, C]) Reset()

func (SoA3[A, B, C]) Rows 

func (columns SoA3[A, B, C]) Rows() []Row3[A, B, C]

type Stats 

type Stats struct {
	Capacity    int
	Used        int
	Peak        int
	Allocations int
	Generation  uint64
	Closed      bool
}

type StoragePolicy added in v0.211.0 

type StoragePolicy interface {
	// contains filtered or unexported methods
}

type StoragePolicyCases added in v0.211.0 

type StoragePolicyCases[R any] struct {
	PlatformStorage func() R
	ManagedStorage  func() R
}

StoragePolicyCases selects one handler per StoragePolicy variant for StoragePolicyFold.

type StoragePolicyEqOverrides added in v0.211.0 

type StoragePolicyEqOverrides struct {
	PlatformStorage func(x, y PlatformStorage) (eq, handled bool)
	ManagedStorage  func(x, y ManagedStorage) (eq, handled bool)
}

StoragePolicyEqOverrides carries optional per-variant hooks for StoragePolicyEqualWith. A hook returning handled=false falls through to the derived comparison.

type ZeroOnRelease 

type ZeroOnRelease struct{}

ZeroOnRelease is the secure default and the zero value after erasure.

type ZeroPolicy 

type ZeroPolicy interface {
	// contains filtered or unexported methods
}

type ZeroPolicyCases 

type ZeroPolicyCases[R any] struct {
	ZeroOnRelease     func() R
	PreserveOnRelease func() R
}

ZeroPolicyCases selects one handler per ZeroPolicy variant for ZeroPolicyFold.

type ZeroPolicyEqOverrides 

type ZeroPolicyEqOverrides struct {
	ZeroOnRelease     func(x, y ZeroOnRelease) (eq, handled bool)
	PreserveOnRelease func(x, y PreserveOnRelease) (eq, handled bool)
}

ZeroPolicyEqOverrides carries optional per-variant hooks for ZeroPolicyEqualWith. A hook returning handled=false falls through to the derived comparison.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.