mmap-go

mmap-go gives Go programs cross-platform access to memory-mapped files through a single MMap type built on plain []byte. Instead of hand-rolling syscall-level mmap or CreateFileMapping calls for each operating system, the package abstracts Linux, macOS, the BSDs, Windows, Plan 9, and WebAssembly behind one Map/MapRegion API, so code that treats a mapped file as a byte slice runs unmodified across platforms.

Under the hood it dispatches to unix.Mmap via golang.org/x/sys/unix on POSIX systems and to CreateFileMapping/MapViewOfFile on Windows, tracking handle metadata separately so the public API can stay a plain byte slice. Read-only, read-write, and copy-on-write mapping modes are supported alongside anonymous (non-file-backed) mappings, page locking, and explicit flush-to-disk control.

What You Get

• A single Map/MapRegion API that works identically on Linux, macOS, BSD, Windows, Plan 9, and WebAssembly
• An MMap type that behaves like a plain []byte, so mapped files slot into existing byte-slice-based code with no adapter layer
• Support for read-only, read-write, and copy-on-write mapping modes, plus anonymous (non-file-backed) memory
• Explicit Lock/Unlock/Flush/Unmap methods for controlling residency and durability of mapped memory

Common Use Cases

• Memory-mapping large files (logs, databases, indexes) to read them without loading the whole file into a Go buffer
• Building embedded storage engines or key-value stores that need direct byte-level access to on-disk data
• Sharing or allocating memory outside the Go garbage collector’s heap via anonymous mmap regions
• Writing cross-platform tools that need mmap behavior on both Unix-like systems and Windows without maintaining separate build-tagged code paths

Under The Hood

Architecture The package is split by Go build tags into one file per platform family (mmap_unix.go, mmap_windows.go, mmap_plan9.go, mmap_wasm.go), each implementing a small private contract (mmap, flush, lock, unlock, unmap) that the shared mmap.go file dispatches to through the public Map/MapRegion functions and the MMap byte-slice type; this keeps the public surface tiny and platform differences fully contained, with no dependency injection needed since the package is a thin leaf wrapper over syscalls.

Tech Stack Written in Go (module targets Go 1.17) with a single external dependency, golang.org/x/sys, used for the raw unix and windows syscall bindings; there is no additional build tooling beyond the standard go toolchain, and GitHub Actions runs the test suite across Linux, macOS, and Windows on every push.

Code Quality mmap_test.go exercises real behavior — mapping and unmapping, read/write round-trips, copy-on-write isolation, non-zero-offset mapping, and anonymous mappings — using the standard testing package, while example_test.go doubles as runnable documentation via Example functions. Errors from OS calls are wrapped with os.NewSyscallError for consistent error messages. Coverage is solid for a package this size, though narrow: there’s no fuzzing and no linter configuration checked into the repo.

What Makes It Unique The package isn’t attempting anything novel technically — it’s a faithful, well-scoped polyfill that unifies syscall-level mmap and the Windows CreateFileMapping/MapViewOfFile pair behind one interface, following the same shape as several other language mmap wrappers. Its value is narrowness and stability rather than innovation: a minimal, long-lived API surface that Go programs can depend on without writing their own per-platform mmap glue.