manual

README

manual

Manual provides abstractions and implementations to work with manual memory management.

This repo is intended to be used to demonstrate manual memory management principles to students in the Go programming language.

The Allocator interface

// Allocator is the interface of a manual memory allocator.
type Allocator interface {
	// Malloc allocates a slab of memory of argument number of bytes.
	// The pointer returned points to the start address of the slab.
	// If the memory fails to allocate then nil is returned.
	Malloc(sizeInBytes int) unsafe.Pointer
	// Free receives a point previously allocated by Malloc and frees it.
	// After the memory is freed the pointer should be discarded and no other operation done with it.
	Free(toBeFreed unsafe.Pointer) error
}

Example

func newAllocator() manual.Allocator {
    var ta manual.TestAllocator // Ready to use as zero value.
    ta.SetMaxMemory(1024)
    return &ta
}

func doWork(alloc manual.Allocator) error {
    slice := manual.Malloc[int](alloc, 20)
    if slice == nil {
        return errors.New("allocation failed")
    }
    // do work with slice.
    err := manual.Free(alloc, slice)
    return err
}

Installation

How to install package with newer versions of Go (+1.16):

go mod download github.com/soypat/manual@latest

Documentation

Index

• func Free[T any](alloc Allocator, b []T) error
• func Malloc[T any](alloc Allocator, n int) []T
• type Allocator
• type TestAllocator
  • func (a *TestAllocator) Free(p unsafe.Pointer) error
  • func (a *TestAllocator) Malloc(n int) unsafe.Pointer
  • func (a *TestAllocator) SetMaxFree(maxFreeMemInBytes int)
  • func (a *TestAllocator) SetMaxMemory(maxmemInBytes int)
  • func (a *TestAllocator) SetOnFreeCallback(onFree func(b []byte))

Functions

func Free

func Free[T any](alloc Allocator, b []T) error

Free calls [Allocator.Free] on the data portion of the buffer. Keep in mind the buffer must be the same one returned my Malloc. If the slice start pointer has been resliced Free will fail.

func Malloc

func Malloc[T any](alloc Allocator, n int) []T

Malloc provides generic slice allocation similar to the `make` built in.

Types

type Allocator

type Allocator interface {
	// Malloc allocates a slab of memory of argument number of bytes.
	// The pointer returned points to the start address of the slab.
	// If the memory fails to allocate then nil is returned.
	Malloc(sizeInBytes int) unsafe.Pointer
	// Free receives a point previously allocated by Malloc and frees it.
	// After the memory is freed the pointer should be discarded and no other operation done with it.
	Free(toBeFreed unsafe.Pointer) error
}

Allocator is the interface of a manual memory allocator.

type TestAllocator

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

TestAllocator is a simple implementation of an Allocator. It has the added complexity of being able to reuse freed memory later on to potentially detect use-after-free and double-free bugs.

func (*TestAllocator) Free

func (a *TestAllocator) Free(p unsafe.Pointer) error

Free implements [Allocator.Free].

func (*TestAllocator) Malloc

func (a *TestAllocator) Malloc(n int) unsafe.Pointer

Malloc implements [Allocator.Malloc].

func (*TestAllocator) SetMaxFree

func (a *TestAllocator) SetMaxFree(maxFreeMemInBytes int)

SetMaxFree sets the maximum amount of freed memory to have allocated and ready for reuse. Set to zero for limitless memory. Set to -1 to disable freed memory reuse.

func (*TestAllocator) SetMaxMemory

func (a *TestAllocator) SetMaxMemory(maxmemInBytes int)

SetMaxMemory sets the maximum amount of memory the allocator can have allocated, combined between live and freed. Set to zero to disable memory limits.

func (*TestAllocator) SetOnFreeCallback

func (a *TestAllocator) SetOnFreeCallback(onFree func(b []byte))

SetOnFreeCallback is called on TestAllocator.Free argument buffer after it successfully finds the memory to free.