mmap

README

mmap-go

mmap-go is a portable mmap package for the Go programming language.

Operating System Support

This package is tested using GitHub Actions on Linux, macOS, and Windows. It should also work on other Unix-like platforms, but hasn't been tested with them. I'm interested to hear about the results.

This package compiles for Plan 9 and WebAssembly, but its functions always return errors.

Related functions such as mprotect and mincore aren't included. I haven't found a way to implement them on Windows without introducing significant complexity. If you're running on a Unix-like platform and really need these features, it should still be possible to implement them on top of this package via syscall.

Documentation

Overview

Package mmap allows mapping files into memory. It tries to provide a simple, reasonably portable interface, but doesn't go out of its way to abstract away every little platform detail. This specifically means:

• forked processes may or may not inherit mappings
• a file's timestamp may or may not be updated by writes through mappings
• specifying a size larger than the file's actual size can increase the file's size
• If the mapped file is being modified by another process while your program's running, don't expect consistent results between platforms

Index

• Constants
• type MMap
  • func Map(f *os.File, prot, flags int) (MMap, error)
  • func MapRegion(f *os.File, length int, prot, flags int, offset int64) (MMap, error)
  • func (m MMap) Flush() error
  • func (m MMap) Lock() error
  • func (m MMap) Unlock() error
  • func (m *MMap) Unmap() error

Examples

• Map
• MapRegion

Constants

const (
	// RDONLY maps the memory read-only.
	// Attempts to write to the MMap object will result in undefined behavior.
	RDONLY = 0
	// RDWR maps the memory as read-write. Writes to the MMap object will update the
	// underlying file.
	RDWR = 1 << iota
	// COPY maps the memory as copy-on-write. Writes to the MMap object will affect
	// memory, but the underlying file will remain unchanged.
	COPY
	// If EXEC is set, the mapped memory is marked as executable.
	EXEC
)

const (
	// If the ANON flag is set, the mapped memory will not be backed by a file.
	ANON = 1 << iota
)

Types

type MMap

type MMap []byte

MMap represents a file mapped into memory.

func Map

func Map(f *os.File, prot, flags int) (MMap, error)

Map maps an entire file into memory. If ANON is set in flags, f is ignored.

Example

f, err := os.OpenFile("notes.txt", os.O_RDWR|os.O_CREATE, 0755)
if err != nil {
	log.Fatal(err)
}
_, err = f.WriteString("Hello, world")
if err != nil {
	log.Fatal(err)
}
// The file must be closed, even after calling Unmap.
defer f.Close()

m, err := mmap.Map(f, mmap.RDWR, 0)
if err != nil {
	log.Fatal(err)
}

// m acts as a writable slice of bytes that is a view into the open file, notes.txt.
// It is sized to the file contents automatically.
fmt.Println(string(m))

// The Unmap method should be called when finished with it to avoid leaking memory
// and to ensure that writes are flushed to disk.
if err := m.Unmap(); err != nil {
	log.Fatal(err)
}

// Hello, world

func MapRegion

func MapRegion(f *os.File, length int, prot, flags int, offset int64) (MMap, error)

MapRegion maps part of a file into memory. The offset parameter must be a multiple of the system's page size. If length < 0, the entire file will be mapped. If ANON is set in flags, f is ignored.

Example

m, err := mmap.MapRegion(nil, 100, mmap.RDWR, mmap.ANON, 0)
if err != nil {
	log.Fatal(err)
}
// m acts as a writable slice of bytes that is not managed by the Go runtime.
fmt.Println(len(m))

// Because the region is not managed by the Go runtime, the Unmap method should
// be called when finished with it to avoid leaking memory.
if err := m.Unmap(); err != nil {
	log.Fatal(err)
}

Output:

100

func (MMap) Flush

func (m MMap) Flush() error

Flush synchronizes the mapping's contents to the file's contents on disk.

func (MMap) Lock

func (m MMap) Lock() error

Lock keeps the mapped region in physical memory, ensuring that it will not be swapped out.

func (MMap) Unlock

func (m MMap) Unlock() error

Unlock reverses the effect of Lock, allowing the mapped region to potentially be swapped out. If m is already unlocked, aan error will result.

func (*MMap) Unmap

func (m *MMap) Unmap() error

Unmap deletes the memory mapped region, flushes any remaining changes, and sets m to nil. Trying to read or write any remaining references to m after Unmap is called will result in undefined behavior. Unmap should only be called on the slice value that was originally returned from a call to Map. Calling Unmap on a derived slice may cause errors.