Memory-Mapped Files
TL;DR
Explanation
Memory mapping (mmap on Linux) creates a direct mapping between a file on disk and a region of virtual memory. When a process reads from that address range, the OS transparently loads the relevant page from disk via a page fault. Writes modify the page in memory and the OS flushes them to disk asynchronously. This eliminates the user-to-kernel copy that standard file I/O requires, reducing syscall overhead for large sequential reads. Multiple processes mapping the same file share the underlying pages, enabling efficient IPC (inter-process communication) without explicit message passing. PHP itself does not expose mmap directly, but it is used internally by opcache to share the compiled opcode cache between FPM workers — all workers read from the same shared memory region rather than each maintaining a private copy. SQLite uses mmap for its WAL-mode readers. PHP extensions can use mmap via FFI or C extensions for performance-critical work.
Watch Out
Common Misconception
Why It Matters
Common Mistakes
- Assuming mmap is always the fastest I/O method — random single-byte reads across a large mapping cause repeated page faults that are slower than buffered read().
- Mapping very large files on 32-bit systems — virtual address space is limited to ~3 GB, making large mappings impractical or impossible.
- Not accounting for dirty page writeback latency — a write to a mapped page is not on disk until the OS flushes it, which is asynchronous by default.
Avoid When
- Avoid mmap for small files — the setup overhead and page table entries outweigh the benefit vs file_get_contents().
- Do not use mmap for append-heavy workloads — extending a mapping requires re-mapping, which is expensive.
When To Use
- Use mmap for large sequential reads of files that exceed available RAM — the OS streams pages in and evicts them transparently.
- Use shared anonymous mappings for IPC between processes on the same host where a message queue would add unnecessary overhead.
- Tune opcache.memory_consumption based on your codebase size — it uses mmap internally and insufficient size causes re-compilation.
Code Examples
; opcache too small — workers silently recompile scripts on every request:
opcache.memory_consumption = 64 ; MB — too small for a 500-file app
opcache.max_accelerated_files = 2000; Size to fit entire compiled codebase + headroom:
; Check current usage: opcache_get_status()['memory_usage']
opcache.memory_consumption = 256 ; MB
opcache.max_accelerated_files = 10000
opcache.validate_timestamps = 0 ; production: disable stat() per request