Memory-Mapped Files

Memory-mapped files offer a powerful mechanism for interacting with files by treating their contents as if they were directly present in memory. This technique can significantly improve performance in certain scenarios, particularly when dealing with large files or when inter-process communication is required. Instead of using standard file I/O operations like fread and fwrite, you map a portion of a file (or the entire file) into the process’s virtual address space. This allows you to access and modify the file’s contents using pointers and normal memory access operations.

What is Memory-Mapped Files

Memory-mapped files (MMFs) create a direct mapping between a file on disk and a region of a process’s virtual memory. The operating system handles the loading and saving of data between the file and memory in the background, often using demand paging. This means that only the portions of the file that are actually accessed are loaded into physical memory, conserving resources and improving performance.

In-Depth Explanation:

When you memory-map a file, you’re essentially telling the operating system to create a “window” into the file within your process’s address space. Any changes you make to this “window” are reflected in the underlying file (depending on the mapping mode). The OS manages the synchronization between the memory region and the file on disk.

Edge Cases:

• File Size Changes: If the file size changes after it has been memory-mapped, the behavior can be unpredictable. It’s crucial to handle file size changes carefully, potentially unmapping and remapping the file.
• Concurrency: When multiple processes or threads access the same memory-mapped file, synchronization mechanisms (e.g., mutexes, semaphores) are essential to prevent data corruption.
• File Permissions: The process must have the necessary read and/or write permissions for the file.
• Operating System Limits: Operating systems may impose limits on the number of memory mappings or the total amount of memory that can be mapped.
• Error Handling: MMF operations can fail (e.g., due to insufficient memory, invalid file descriptors). Robust error handling is crucial.

Performance Considerations:

• Reduced Overhead: Memory-mapped files can eliminate the overhead associated with system calls for file I/O, leading to faster access times, especially for random access patterns.
• Demand Paging: The OS only loads the necessary parts of the file into memory, reducing memory consumption and improving performance.
• Cache Effects: The OS caches frequently accessed pages in memory, further improving performance.
• Copy-on-Write: Memory-mapped files can support copy-on-write semantics, where modifications to a mapped region create a private copy of the page, preventing unintended changes to the original file.
• Synchronization Costs: If multiple processes or threads are accessing the same memory-mapped file, the overhead of synchronization mechanisms can impact performance.

Syntax and Usage

C++ itself doesn’t provide direct support for memory-mapped files in the standard library. Instead, you must use operating system-specific APIs. On POSIX-compliant systems (like Linux and macOS), you use functions like mmap, munmap, msync, and ftruncate. On Windows, you use CreateFileMapping, MapViewOfFile, UnmapViewOfFile, and FlushViewOfFile.

POSIX (Linux, macOS):

#include <sys/mman.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <unistd.h>
 
// Map a file into memory
void* mmap(void *addr, size_t length, int prot, int flags, int fd, off_t offset);
 
// Unmap a memory region
int munmap(void *addr, size_t length);
 
// Synchronize a memory region with the file
int msync(void *addr, size_t length, int flags);
 
// Truncate a file to a specified length
int ftruncate(int fd, off_t length);

Windows:

#include <windows.h>
 
// Create a file mapping object
HANDLE CreateFileMapping(HANDLE hFile, LPSECURITY_ATTRIBUTES lpFileMappingAttributes, DWORD flProtect, DWORD dwMaximumSizeHigh, DWORD dwMaximumSizeLow, LPCSTR lpName);
 
// Map a view of a file mapping into the address space of a process
LPVOID MapViewOfFile(HANDLE hFileMappingObject, DWORD dwDesiredAccess, DWORD dwFileOffsetHigh, DWORD dwFileOffsetLow, SIZE_T dwNumberOfBytesToMap);
 
// Unmaps a mapped view of a file from the calling process's address space
BOOL UnmapViewOfFile(LPCVOID lpBaseAddress);
 
// Flushes a specified range of a mapped view of a file to disk
BOOL FlushViewOfFile(LPCVOID lpBaseAddress, SIZE_T dwNumberOfBytesToFlush);

Basic Example (POSIX)

#include <iostream>
#include <fstream>
#include <sys/mman.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <unistd.h>
#include <cerrno>
#include <cstring>
 
int main() {
    const char* filepath = "my_file.txt";
    const char* data = "Hello, Memory-Mapped World!";
    size_t data_len = strlen(data);
 
    // 1. Create and write initial data to the file
    {
        std::ofstream outfile(filepath);
        if (!outfile.is_open()) {
            std::cerr << "Error opening file for writing: " << filepath << std::endl;
            return 1;
        }
        outfile << data;
        outfile.close();
    }
 
 
    int fd = open(filepath, O_RDWR);
    if (fd == -1) {
        std::cerr << "Error opening file: " << strerror(errno) << std::endl;
        return 1;
    }
 
    struct stat sb;
    if (fstat(fd, &sb) == -1) {
        std::cerr << "Error getting file size: " << strerror(errno) << std::endl;
        close(fd);
        return 1;
    }
 
    size_t file_size = sb.st_size;
 
    // 2. Memory-map the file
    char* map = (char*)mmap(nullptr, file_size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
    if (map == MAP_FAILED) {
        std::cerr << "Error mapping file: " << strerror(errno) << std::endl;
        close(fd);
        return 1;
    }
 
    // 3. Modify the mapped region
    strcpy(map, "Modified by memory mapping!");
    msync(map, file_size, MS_SYNC); // Ensure changes are written to disk
 
    // 4. Unmap and close
    if (munmap(map, file_size) == -1) {
        std::cerr << "Error unmapping file: " << strerror(errno) << std::endl;
    }
 
    close(fd);
 
    // Verify data written to file (optional)
    {
        std::ifstream infile(filepath);
        std::string content;
        std::getline(infile, content);
        std::cout << "File content: " << content << std::endl; // Output: Modified by memory mapping!
    }
 
    return 0;
}

Explanation:

1. Create and Initialize File: The code first creates a file named my_file.txt and writes some initial data to it.
2. Open the File: The open function opens the file in read-write mode (O_RDWR).
3. Get File Size: The fstat function retrieves the file’s metadata, including its size, which is stored in the sb structure.
4. Memory Mapping: The mmap function maps the file into memory.
   • nullptr: The operating system chooses the address in memory.
   • file_size: The number of bytes to map.
   • PROT_READ | PROT_WRITE: The mapped region can be read from and written to.
   • MAP_SHARED: Changes made to the mapped region are shared with other processes that have mapped the same file, and are written back to the file. MAP_PRIVATE would create a copy-on-write mapping.
   • fd: The file descriptor.
   • 0: The offset into the file at which the mapping begins (0 means the beginning of the file).
5. Modify the Mapped Region: The strcpy function copies a new string into the mapped region, overwriting the original content.
6. Synchronize with Disk: The msync function ensures that the changes made to the mapped region are written back to the file on disk. MS_SYNC means the function will block until the write is complete.
7. Unmap and Close: The munmap function unmaps the memory region, and the close function closes the file descriptor.
8. Verification: The code reads the content of the file to verify that the changes have been written correctly.

Advanced Example (POSIX - Inter-Process Communication)

#include <iostream>
#include <fstream>
#include <sys/mman.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <unistd.h>
#include <cerrno>
#include <cstring>
#include <sys/wait.h>
 
const char* shared_memory_name = "/my_shared_memory";
const size_t shared_memory_size = 4096;
 
int main(int argc, char* argv[]) {
    bool is_parent = (argc == 1); // Parent process if no arguments
 
    int fd;
    void* shared_memory;
 
    // Create or open shared memory object
    if (is_parent) {
        // Create shared memory object.  Exclusive access.
        fd = shm_open(shared_memory_name, O_CREAT | O_RDWR | O_EXCL, 0666);
        if (fd == -1) {
            std::cerr << "shm_open (create) failed: " << strerror(errno) << std::endl;
            return 1;
        }
        // Size the shared memory
        if (ftruncate(fd, shared_memory_size) == -1) {
            std::cerr << "ftruncate failed: " << strerror(errno) << std::endl;
            close(fd);
            shm_unlink(shared_memory_name); // Cleanup
            return 1;
        }
 
    } else {
        // Open existing shared memory object
        fd = shm_open(shared_memory_name, O_RDWR, 0);
        if (fd == -1) {
            std::cerr << "shm_open (open) failed: " << strerror(errno) << std::endl;
            return 1;
        }
    }
 
    // Map shared memory
    shared_memory = mmap(nullptr, shared_memory_size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
    if (shared_memory == MAP_FAILED) {
        std::cerr << "mmap failed: " << strerror(errno) << std::endl;
        close(fd);
        if(is_parent) shm_unlink(shared_memory_name);
        return 1;
    }
    close(fd); // File descriptor no longer needed after mmap
 
    if (is_parent) {
        // Parent process: write data to shared memory and create child process
        const char* message = "Hello from parent!";
        strncpy(static_cast<char*>(shared_memory), message, shared_memory_size - 1);
        static_cast<char*>(shared_memory)[shared_memory_size - 1] = '\0'; // Null terminate
 
        pid_t pid = fork();
        if (pid == -1) {
            std::cerr << "fork failed: " << strerror(errno) << std::endl;
            munmap(shared_memory, shared_memory_size);
            shm_unlink(shared_memory_name);
            return 1;
        }
 
        if (pid == 0) {
            // Child process: execute itself with an argument to indicate it's the child
            execlp(argv[0], argv[0], "child", nullptr);
            std::cerr << "execlp failed: " << strerror(errno) << std::endl;
            exit(1); // Exit if execlp fails
        } else {
            // Parent process: wait for child to finish
            wait(nullptr);
 
            // Clean up shared memory
            munmap(shared_memory, shared_memory_size);
            shm_unlink(shared_memory_name);
        }
    } else {
        // Child process: read data from shared memory
        std::cout << "Child process received: " << static_cast<char*>(shared_memory) << std::endl;
        munmap(shared_memory, shared_memory_size);
    }
 
    return 0;
}

This example demonstrates inter-process communication (IPC) using shared memory created via shm_open and mmap. The parent process writes a message to the shared memory, and the child process reads the message. The use of shm_unlink by the parent ensures the shared memory object is deleted after the parent and child finish. The use of O_EXCL in the parent prevents race conditions if multiple processes try to create the shared memory simultaneously.

Common Use Cases

• Large File Processing: Reading and processing large files that don’t fit entirely in memory.
• Inter-Process Communication (IPC): Sharing data between processes efficiently.
• Database Systems: Implementing shared buffers for database caching.
• Image and Video Processing: Directly accessing and manipulating image and video data.

Best Practices

• Error Handling: Always check the return values of mmap, munmap, msync, CreateFileMapping, MapViewOfFile, and UnmapViewOfFile for errors.
• File Size Awareness: Ensure that the file size is known and handled correctly, especially when the file might be modified by other processes.
• Synchronization: Use appropriate synchronization mechanisms (mutexes, semaphores) when multiple processes or threads access the same memory-mapped file.
• Unmapping: Always unmap the memory region using munmap or UnmapViewOfFile when it’s no longer needed.
• Flush Modifications: Explicitly flush changes to disk using msync or FlushViewOfFile when necessary to ensure data persistence.
• Use RAII: Wrap the memory mapping and unmapping operations in RAII (Resource Acquisition Is Initialization) classes to ensure proper cleanup, even in the presence of exceptions.

Common Pitfalls

• Forgetting to Unmap: Failing to unmap the memory region can lead to resource leaks.
• Incorrect File Size Handling: Mapping a region larger than the file can result in errors or unexpected behavior.
• Lack of Synchronization: Ignoring synchronization requirements when multiple processes or threads access the same memory-mapped file can lead to data corruption.
• Assuming Immediate Persistence: Changes to the mapped region are not necessarily written to disk immediately. Use msync or FlushViewOfFile to ensure persistence.
• Ignoring Errors: Not checking for errors from the memory mapping functions can mask serious problems.

Key Takeaways

• Memory-mapped files provide a mechanism for treating files as memory, improving performance for certain I/O operations.
• Operating system-specific APIs (e.g., mmap on POSIX, CreateFileMapping on Windows) are required.
• Proper error handling, file size management, and synchronization are essential for reliable and correct usage.
• Memory-mapped files are useful for large file processing, inter-process communication, and other performance-critical applications.