std: Add std.fs.MemoryMap.

This new type provides a cross platform memory mapping API which
encompasses the common subset of both POSIX and Windows APIs.

Author: gcoakes

lib/std/fs.zig

@@ -17,6 +17,7 @@ const is_darwin = native_os.isDarwin();
 pub const AtomicFile = @import("fs/AtomicFile.zig");
 pub const Dir = @import("fs/Dir.zig");
 pub const File = @import("fs/File.zig");
+pub const MemoryMap = @import("fs/MemoryMap.zig");
 pub const path = @import("fs/path.zig");
 
 pub const has_executable_bit = switch (native_os) {
@@ -710,6 +711,7 @@ test {
     _ = &AtomicFile;
     _ = &Dir;
     _ = &File;
+    _ = &MemoryMap;
     _ = &path;
     _ = @import("fs/test.zig");
     _ = @import("fs/get_app_data_dir.zig");

lib/std/fs/MemoryMap.zig

@@ -0,0 +1,181 @@
+const std = @import("../std.zig");
+const builtin = @import("builtin");
+
+const MemoryMap = @This();
+
+/// An OS-specific reference to a kernel object for this mapping.
+handle: switch (builtin.os.tag) {
+    .windows => std.os.windows.HANDLE,
+    else => void,
+},
+/// The region of virtual memory in which the file is mapped.
+///
+/// Accesses to this are subject to the protection semantics specified upon
+/// initialization of the mapping. Failure to abide by those semantics has undefined
+/// behavior (though should be well-defined by the OS).
+mapped: []align(std.mem.page_size) volatile u8,
+
+test MemoryMap {
+    if (builtin.os.tag == .wasi) return error.SkipZigTest;
+
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+
+    var file = try tmp.dir.createFile("mmap.bin", .{
+        .exclusive = true,
+        .truncate = true,
+        .read = true,
+    });
+    defer file.close();
+
+    const magic = "\xde\xca\xfb\xad";
+    try file.writeAll(magic);
+
+    const len = try file.getEndPos();
+
+    var view = try MemoryMap.init(file, .{ .length = @intCast(len) });
+    defer view.deinit();
+
+    try std.testing.expectEqualSlices(u8, magic, @volatileCast(view.mapped));
+}
+
+pub const InitOptions = struct {
+    protection: ProtectionFlags = .{},
+    exclusivity: Exclusivity = .private,
+    /// The desired offset of the mapping.
+    ///
+    /// The backing file must be of at least `offset` size.
+    offset: usize = 0,
+    /// The desired length of the mapping.
+    ///
+    /// The backing file must be of at least `offset + length` size.
+    length: usize,
+    hint: ?[*]align(std.mem.page_size) u8 = null,
+};
+
+/// A description of OS protections to be applied to a memory-mapped region.
+pub const ProtectionFlags = struct {
+    write: bool = false,
+    execute: bool = false,
+};
+
+pub const Exclusivity = enum {
+    /// The file's content may be read or written by external processes.
+    shared,
+    /// The file's content is exclusive to this process.
+    private,
+};
+
+/// Create a memory-mapped view into `file`.
+///
+/// Asserts `opts.length` is non-zero.
+pub fn init(file: std.fs.File, opts: InitOptions) !MemoryMap {
+    std.debug.assert(opts.length > 0);
+    switch (builtin.os.tag) {
+        .wasi => @compileError("MemoryMap not supported on WASI OS; see also " ++
+            "https://github.com/WebAssembly/WASI/issues/304"),
+        .windows => {
+            // Create the kernel resource for the memory mapping.
+            const prot: std.os.windows.DWORD = switch (opts.protection.execute) {
+                true => switch (opts.protection.write) {
+                    true => std.os.windows.PAGE_EXECUTE_READWRITE,
+                    false => std.os.windows.PAGE_EXECUTE_READ,
+                },
+                false => switch (opts.protection.write) {
+                    true => std.os.windows.PAGE_READWRITE,
+                    false => std.os.windows.PAGE_READONLY,
+                },
+            };
+            const handle = try std.os.windows.CreateFileMapping(
+                file.handle,
+                null,
+                prot,
+                opts.length,
+                null,
+            );
+            errdefer std.os.windows.CloseHandle(handle);
+
+            // Convert the public options into Windows specific options.
+            var flags: std.os.windows.DWORD = std.os.windows.FILE_MAP_READ;
+            if (opts.protection.write)
+                flags |= std.os.windows.FILE_MAP_WRITE;
+            if (opts.protection.execute)
+                flags |= std.os.windows.FILE_MAP_EXECUTE;
+            if (opts.exclusivity == .private)
+                flags |= std.os.windows.FILE_MAP_COPY;
+
+            // Create the mapping.
+            const mapped = try std.os.windows.MapViewOfFile(
+                handle,
+                flags,
+                opts.offset,
+                opts.length,
+                opts.hint,
+            );
+
+            return .{
+                .handle = handle,
+                .mapped = mapped,
+            };
+        },
+        else => {
+            // The man page indicates the flags must be either `NONE` or an OR of the
+            // flags. That doesn't explicitly state that the absence of those flags is
+            // the same as `NONE`, so this static assertion is made. That'll break the
+            // build rather than behaving unexpectedly if some weird system comes up.
+            comptime std.debug.assert(std.posix.PROT.NONE == 0);
+
+            // Convert the public options into POSIX specific options.
+            var prot: u32 = std.posix.PROT.READ;
+            if (opts.protection.write)
+                prot |= std.posix.PROT.WRITE;
+            if (opts.protection.execute)
+                prot |= std.posix.PROT.EXEC;
+            const flags: std.posix.MAP = .{
+                .TYPE = switch (opts.exclusivity) {
+                    .shared => .SHARED,
+                    .private => .PRIVATE,
+                },
+            };
+
+            // Create the mapping.
+            const mapped = try std.posix.mmap(
+                opts.hint,
+                opts.length,
+                prot,
+                @bitCast(flags),
+                file.handle,
+                opts.offset,
+            );
+
+            return .{
+                .handle = {},
+                .mapped = mapped,
+            };
+        },
+    }
+}
+
+/// Unmap the file from virtual memory and deallocate kernel resources.
+///
+/// Invalidates references to `self.mapped`.
+pub fn deinit(self: MemoryMap) void {
+    switch (builtin.os.tag) {
+        .windows => {
+            std.os.windows.UnmapViewOfFile(@volatileCast(self.mapped.ptr));
+            std.os.windows.CloseHandle(self.handle);
+        },
+        else => {
+            std.posix.munmap(@volatileCast(self.mapped));
+        },
+    }
+}
+
+/// Reinterpret `self.mapped` as `T`.
+///
+/// The returned pointer is aligned to the beginning of the mapping. The mapping may be
+/// larger than `T`. The caller is responsible for determining whether volatility can be
+/// stripped away through external synchronization.
+pub inline fn cast(self: MemoryMap, comptime T: type) *align(std.mem.page_size) volatile T {
+    return std.mem.bytesAsValue(T, self.mapped[0..@sizeOf(T)]);
+}

lib/std/os/windows.zig

@@ -201,8 +201,11 @@ pub fn MapViewOfFile(
         size,
         hint,
     );
-    if (ptr) |p|
-        return @alignCast(p[0..size]);
+    if (ptr) |p| {
+        const cast: [*]align(std.mem.page_size) volatile u8 =
+            @alignCast(@ptrCast(p));
+        return @alignCast(cast[0..size]);
+    }
     switch (GetLastError()) {
         else => |err| return unexpectedError(err),
     }