arena

Documentation

Overview

Package arena implements a memory arena.

Index

• func Put(ctx context.Context, d Arena) context.Context
• type Arena
  • func Get(ctx context.Context) Arena
  • func New() Arena
  • func (a Arena) Allocate(size, alignment int) unsafe.Pointer
  • func (a Arena) Dispose()
  • func (a Arena) Free(ptr unsafe.Pointer)
  • func (a Arena) NewWriter(size, alignment int) *Writer
  • func (a Arena) Reallocate(ptr unsafe.Pointer, size, alignment int) unsafe.Pointer
  • func (a Arena) Stats() Stats
• type Offsetable
  • func (o *Offsetable) AlignUp(n int)
• type Reader
  • func NewReader(ptr unsafe.Pointer) *Reader
  • func (r *Reader) Read(dst unsafe.Pointer, size int)
• type Stats
  • func (s Stats) String() string
• type Writer
  • func (w *Writer) Pointer() unsafe.Pointer
  • func (w *Writer) Reset()
  • func (w *Writer) Write(src unsafe.Pointer, size int)

Functions

func Put

func Put(ctx context.Context, d Arena) context.Context

Put amends a Context by attaching a Arena reference to it.

Types

type Arena

type Arena struct{ Pointer unsafe.Pointer }

Arena is a native memory allocator that owns each of the allocations made by Allocate() and Reallocate(). If there are any outstanding allocations when the Arena is disposed then these allocations are automatically freed. Because the memory is allocated outside of the Go environment it is important to explicity free unused memory - either by calling Free() or calling Dispose() on the Arena. Failing to Dispose() the arena will leak memory.

func Get

func Get(ctx context.Context) Arena

Get returns the Arena attached to the given context.

func New

func New() Arena

New constructs a new arena. You must call Dispose to free the arena object and any arena-owned allocations.

func (Arena) Allocate

func (a Arena) Allocate(size, alignment int) unsafe.Pointer

Allocate returns a pointer to a new arena-owned, contiguous block of memory of the specified size and alignment.

func (Arena) Dispose

func (a Arena) Dispose()

Dispose destructs and frees the arena and all arena-owned allocations.

func (Arena) Free

func (a Arena) Free(ptr unsafe.Pointer)

Free releases the memory at ptr, which must have been previously allocated by this arena.

func (Arena) NewWriter

func (a Arena) NewWriter(size, alignment int) *Writer

NewWriter returns a new Writer to a new arena allocated buffer of the initial size. The native buffer may grow if the writer exceeds the size of the buffer. The buffer will always be of the specified alignment in memory. The once the native buffer is no longer needed, the pointer returned by Pointer() should be passed to Arena.Free().

func (Arena) Reallocate

func (a Arena) Reallocate(ptr unsafe.Pointer, size, alignment int) unsafe.Pointer

Reallocate reallocates the memory at ptr to the new size and alignment. ptr must have been allocated from this arena or be nil.

func (Arena) Stats

func (a Arena) Stats() Stats

Stats returns statistics of the current state of the Arena.

type Offsetable

type Offsetable struct{ Offset int }

Offsetable is used as an anonymous field of types that require a current offset value.

func (*Offsetable) AlignUp

func (o *Offsetable) AlignUp(n int)

AlignUp rounds-up the current offset so that is is a multiple of n.

type Reader

type Reader struct {
	Offsetable // The current read-offset in bytes.
	// contains filtered or unexported fields
}

Reader provides the Read method to read native buffer data. Use NewReader() to construct.

func NewReader

func NewReader(ptr unsafe.Pointer) *Reader

NewReader returns a new Reader to the native-buffer starting at ptr.

func (*Reader) Read

func (r *Reader) Read(dst unsafe.Pointer, size int)

Read copies size bytes from the current read offset to dst. Upon returning, the read offset is incremented by size bytes.

type Stats

type Stats struct {
	NumAllocations    int
	NumBytesAllocated int
}

Stats holds statistics of an Arena.

func (Stats) String

func (s Stats) String() string

type Writer

type Writer struct {
	Offsetable // The current write-offset in bytes.
	// contains filtered or unexported fields
}

Writer provides methods to help allocate and populate a native buffer with data. Use Arena.Writer() to construct.

func (*Writer) Pointer

func (w *Writer) Pointer() unsafe.Pointer

Pointer returns the base address of the native buffer for the writer. Calling Pointer() freezes the writer - once called no more writes to the buffer can be made, unless Reset() is called. Freezing attempts to reduce the chance of the stale pointer being used after a buffer reallocation.

func (*Writer) Reset

func (w *Writer) Reset()

Reset sets the write offset back to the start of the buffer and unfreezes the writer. This allows for efficient reuse of the writer's native buffer.

func (*Writer) Write

func (w *Writer) Write(src unsafe.Pointer, size int)

Write copies size bytes from src to the current writer's write offset. If there is not enough space in the buffer for the write, then the buffer is grown via reallocation. Upon returning, the write offset is incremented by size bytes.