Architecture dependent routines for virtual memory. More...

Include dependency graph for virtualMemory.h:

Enumerations
enum	ArchMemoryProtection { ArchProtectNoAccess , ArchProtectReadOnly , ArchProtectReadWrite , ArchProtectReadWriteCopy }
	Memory protection options, see ArchSetMemoryProtection(). More...

Functions
ARCH_API void *	ArchReserveVirtualMemory (size_t numBytes)
	Reserve `numBytes` bytes of virtual memory.

ARCH_API bool	ArchCommitVirtualMemoryRange (void *start, size_t numBytes)
	Make the range of `numBytes` bytes starting at `start` available for reading and writing.

ARCH_API bool	ArchFreeVirtualMemory (void *start, size_t numBytes)
	Return memory obtained with ArchReserveVirtualMemory() to the system.

ARCH_API bool	ArchSetMemoryProtection (void const *start, size_t numBytes, ArchMemoryProtection protection)
	Change the memory protection on the pages containing `start` through `start` + `numBytes` to `protection`.

Detailed Description

Architecture dependent routines for virtual memory.

The functions here report failure by return value. On POSIX systems the underlying mmap(), mprotect() or munmap() call also sets errno; on Windows the underlying VirtualAlloc(), VirtualProtect() or VirtualFree() call reports through GetLastError() and leaves errno untouched.

Ranges are handled at page granularity: these functions operate on every page that [start, start + numBytes) touches, and on no others. Subranges of a single reservation are therefore independent only where their boundaries are page-aligned; two subranges that share a page are always committed and protected together. Use ArchGetPageSize() to reason about such boundaries when needed. Alignment is key, not just size: a page-sized range starting mid-page touches two pages.

numBytes must be nonzero throughout: zero is not handled consistently across platforms.

Definition in file virtualMemory.h.

Enumeration Type Documentation

◆ ArchMemoryProtection

enum ArchMemoryProtection

Memory protection options, see ArchSetMemoryProtection().

ArchProtectReadWriteCopy applies only to a private file-backed mapping. On POSIX it is identical to ArchProtectReadWrite; on Windows it maps to PAGE_WRITECOPY, which is meaningful for a view of a file mapping opened with FILE_MAP_COPY and is not applicable to memory from ArchReserveVirtualMemory().

Definition at line 72 of file virtualMemory.h.

Function Documentation

◆ ArchCommitVirtualMemoryRange()

ARCH_API bool ArchCommitVirtualMemoryRange	(	void *	start,
		size_t	numBytes )

Make the range of numBytes bytes starting at start available for reading and writing.

The range must be within one previously reserved by ArchReserveVirtualMemory(). Newly committed memory reads as zero. It is not an error to commit a range that was previously partly or fully committed, and doing so preserves the contents of the part that was. Return false in case of an error.

◆ ArchFreeVirtualMemory()

ARCH_API bool ArchFreeVirtualMemory	(	void *	start,
		size_t	numBytes )

Return memory obtained with ArchReserveVirtualMemory() to the system.

The start argument must be the value returned from a previous call to ArchReserveVirtualMemory(), and numBytes must match the argument from that call. The whole reservation is freed, committed subranges included. Memory within the range may not be accessed after this call. Return false in case of an error.

A mismatched numBytes is not diagnosed consistently: POSIX either fails or unmaps the wrong range, while Windows ignores numBytes and releases the whole reservation regardless.

◆ ArchReserveVirtualMemory()

ARCH_API void * ArchReserveVirtualMemory ( size_t numBytes )

Reserve numBytes bytes of virtual memory.

The memory is inaccessible until ArchCommitVirtualMemoryRange() is called on subranges to write to and read from. Return nullptr in case of an error.

◆ ArchSetMemoryProtection()

ARCH_API bool ArchSetMemoryProtection	(	void const *	start,
		size_t	numBytes,
		ArchMemoryProtection	protection )

Change the memory protection on the pages containing start through start + numBytes to protection.

Return true if the protection is changed successfully. Return false in case of an error. Changing protection does not disturb the contents of the pages, and in particular ArchProtectNoAccess does not release them.

Enumerations

Functions