memory

README

memory

Package memory implements a memory allocator.

Build status

available at https://modern-c.appspot.com/-/builder/?importpath=modernc.org%2fmemory

Installation

$ go get modernc.org/memory

Documentation: godoc.org/modernc.org/memory

Documentation

Overview

Package memory implements a memory allocator.

Build status

available at https://modern-c.appspot.com/-/builder/?importpath=modernc.org%2fmemory

Changelog

2017-10-03 Added alternative, unsafe.Pointer-based API.

Package memory implements a memory allocator.

Changelog

2017-10-03 Added alternative, unsafe.Pointer-based API.

Benchmarks

jnml@3900x:~/src/modernc.org/memory$ date ; go version ; go test -run @ -bench . -benchmem |& tee log
Mon Sep 25 16:02:02 CEST 2023
go version go1.21.1 linux/amd64
goos: linux
goarch: amd64
pkg: modernc.org/memory
cpu: AMD Ryzen 9 3900X 12-Core Processor
BenchmarkFree16-24             	123506772	         9.802 ns/op	       0 B/op	       0 allocs/op
BenchmarkFree32-24             	73853230	        15.08 ns/op	       0 B/op	       0 allocs/op
BenchmarkFree64-24             	43070334	        25.15 ns/op	       0 B/op	       0 allocs/op
BenchmarkCalloc16-24           	59353304	        18.92 ns/op	       0 B/op	       0 allocs/op
BenchmarkCalloc32-24           	39415004	        29.00 ns/op	       0 B/op	       0 allocs/op
BenchmarkCalloc64-24           	35825725	        32.02 ns/op	       0 B/op	       0 allocs/op
BenchmarkGoCalloc16-24         	38274313	        26.99 ns/op	      16 B/op	       1 allocs/op
BenchmarkGoCalloc32-24         	44590477	        33.06 ns/op	      32 B/op	       1 allocs/op
BenchmarkGoCalloc64-24         	44233016	        37.20 ns/op	      64 B/op	       1 allocs/op
BenchmarkMalloc16-24           	145736911	         7.720 ns/op	       0 B/op	       0 allocs/op
BenchmarkMalloc32-24           	128898334	         7.887 ns/op	       0 B/op	       0 allocs/op
BenchmarkMalloc64-24           	149569483	         7.994 ns/op	       0 B/op	       0 allocs/op
BenchmarkUintptrFree16-24      	117043012	         9.205 ns/op	       0 B/op	       0 allocs/op
BenchmarkUintptrFree32-24      	77399617	        14.20 ns/op	       0 B/op	       0 allocs/op
BenchmarkUintptrFree64-24      	48770785	        25.04 ns/op	       0 B/op	       0 allocs/op
BenchmarkUintptrCalloc16-24    	79257636	        15.44 ns/op	       0 B/op	       0 allocs/op
BenchmarkUintptrCalloc32-24    	49644562	        23.62 ns/op	       0 B/op	       0 allocs/op
BenchmarkUintptrCalloc64-24    	39854710	        28.22 ns/op	       0 B/op	       0 allocs/op
BenchmarkUintptrMalloc16-24    	252987727	         4.525 ns/op	       0 B/op	       0 allocs/op
BenchmarkUintptrMalloc32-24    	241423840	         4.433 ns/op	       0 B/op	       0 allocs/op
BenchmarkUintptrMalloc64-24    	256450324	         4.669 ns/op	       0 B/op	       0 allocs/op
PASS
ok  	modernc.org/memory	93.178s
jnml@3900x:~/src/modernc.org/memory$

Index

• func UintptrUsableSize(p uintptr) (r int)
• func UnsafeUsableSize(p unsafe.Pointer) (r int)
• func UsableSize(p *byte) (r int)
• type Allocator
  • func (a *Allocator) Calloc(size int) (r []byte, err error)
  • func (a *Allocator) Close() (err error)
  • func (a *Allocator) Free(b []byte) (err error)
  • func (a *Allocator) Malloc(size int) (r []byte, err error)
  • func (a *Allocator) Realloc(b []byte, size int) (r []byte, err error)
  • func (a *Allocator) UintptrCalloc(size int) (r uintptr, err error)
  • func (a *Allocator) UintptrFree(p uintptr) (err error)
  • func (a *Allocator) UintptrMalloc(size int) (r uintptr, err error)
  • func (a *Allocator) UintptrRealloc(p uintptr, size int) (r uintptr, err error)
  • func (a *Allocator) UnsafeCalloc(size int) (r unsafe.Pointer, err error)
  • func (a *Allocator) UnsafeFree(p unsafe.Pointer) (err error)
  • func (a *Allocator) UnsafeMalloc(size int) (r unsafe.Pointer, err error)
  • func (a *Allocator) UnsafeRealloc(p unsafe.Pointer, size int) (r unsafe.Pointer, err error)

Functions

func UintptrUsableSize

func UintptrUsableSize(p uintptr) (r int)

UintptrUsableSize is like UsableSize except its argument is an uintptr, which must have been returned from UintptrCalloc, UintptrMalloc or UintptrRealloc.

func UnsafeUsableSize

func UnsafeUsableSize(p unsafe.Pointer) (r int)

UnsafeUsableSize is like UsableSize except its argument is an unsafe.Pointer, which must have been returned from UnsafeCalloc, UnsafeMalloc or UnsafeRealloc.

func UsableSize

func UsableSize(p *byte) (r int)

UsableSize reports the size of the memory block allocated at p, which must point to the first byte of a slice returned from Calloc, Malloc or Realloc. The allocated memory block size can be larger than the size originally requested from Calloc, Malloc or Realloc.

Types

type Allocator

type Allocator struct {
	Allocs int // # of allocs.
	Bytes  int // Asked from OS.

	Mmaps int // Asked from OS.
	// contains filtered or unexported fields
}

Allocator allocates and frees memory. Its zero value is ready for use. The exported counters are updated only when build tag memory.counters is present.

func (*Allocator) Calloc

func (a *Allocator) Calloc(size int) (r []byte, err error)

Calloc is like Malloc except the allocated memory is zeroed.

func (*Allocator) Close

func (a *Allocator) Close() (err error)

Close releases all OS resources used by a and sets it to its zero value.

It's not necessary to Close the Allocator when exiting a process.

func (*Allocator) Free

func (a *Allocator) Free(b []byte) (err error)

Free deallocates memory (as in C.free). The argument of Free must have been acquired from Calloc or Malloc or Realloc.

func (*Allocator) Malloc

func (a *Allocator) Malloc(size int) (r []byte, err error)

Malloc allocates size bytes and returns a byte slice of the allocated memory. The memory is not initialized. Malloc panics for size < 0 and returns (nil, nil) for zero size.

It's ok to reslice the returned slice but the result of appending to it cannot be passed to Free or Realloc as it may refer to a different backing array afterwards.

func (*Allocator) Realloc

func (a *Allocator) Realloc(b []byte, size int) (r []byte, err error)

Realloc changes the size of the backing array of b to size bytes or returns an error, if any. The contents will be unchanged in the range from the start of the region up to the minimum of the old and new sizes. If the new size is larger than the old size, the added memory will not be initialized. If b's backing array is of zero size, then the call is equivalent to Malloc(size), for all values of size; if size is equal to zero, and b's backing array is not of zero size, then the call is equivalent to Free(b). Unless b's backing array is of zero size, it must have been returned by an earlier call to Malloc, Calloc or Realloc. If the area pointed to was moved, a Free(b) is done.

func (*Allocator) UintptrCalloc

func (a *Allocator) UintptrCalloc(size int) (r uintptr, err error)

UintptrCalloc is like Calloc except it returns an uintptr.

func (*Allocator) UintptrFree

func (a *Allocator) UintptrFree(p uintptr) (err error)

UintptrFree is like Free except its argument is an uintptr, which must have been acquired from UintptrCalloc or UintptrMalloc or UintptrRealloc.

func (*Allocator) UintptrMalloc

func (a *Allocator) UintptrMalloc(size int) (r uintptr, err error)

UintptrMalloc is like Malloc except it returns an uinptr.

func (*Allocator) UintptrRealloc

func (a *Allocator) UintptrRealloc(p uintptr, size int) (r uintptr, err error)

UintptrRealloc is like Realloc except its first argument is an uintptr, which must have been returned from UintptrCalloc, UintptrMalloc or UintptrRealloc.

func (*Allocator) UnsafeCalloc

func (a *Allocator) UnsafeCalloc(size int) (r unsafe.Pointer, err error)

UnsafeCalloc is like Calloc except it returns an unsafe.Pointer.

func (*Allocator) UnsafeFree

func (a *Allocator) UnsafeFree(p unsafe.Pointer) (err error)

UnsafeFree is like Free except its argument is an unsafe.Pointer, which must have been acquired from UnsafeCalloc or UnsafeMalloc or UnsafeRealloc.

func (*Allocator) UnsafeMalloc

func (a *Allocator) UnsafeMalloc(size int) (r unsafe.Pointer, err error)

UnsafeMalloc is like Malloc except it returns an unsafe.Pointer.

func (*Allocator) UnsafeRealloc

func (a *Allocator) UnsafeRealloc(p unsafe.Pointer, size int) (r unsafe.Pointer, err error)

UnsafeRealloc is like Realloc except its first argument is an unsafe.Pointer, which must have been returned from UnsafeCalloc, UnsafeMalloc or UnsafeRealloc.