OS Virtual Memory

Direct wrappers over VirtualAlloc/mmap for page-level memory control. More...

Functions
usize	mem_os_page_size (void)
	Retrieves the operating system's virtual memory page size.
void *	mem_os_reserve (usize size)
	Reserves a contiguous block of virtual address space.
b32	mem_os_commit (void *ptr, usize size)
	Commits physical RAM to a previously reserved virtual address block.
void	mem_os_decommit (void *ptr, usize size)
	Decommits physical RAM, returning it to the OS.
void	mem_os_release (void *ptr, usize size)
	Releases a reserved virtual address block entirely back to the OS.

Detailed Description

Direct wrappers over VirtualAlloc/mmap for page-level memory control.

Function Documentation

mem_os_commit()

b32 mem_os_commit	(	void *	ptr,
		usize	size )

Commits physical RAM to a previously reserved virtual address block.

The committed memory is zero-initialized by the OS on first access. Commit size is rounded up to the OS page size internally.

Example:

void *mem = mem_os_reserve(GB(1));
// Commit only what we need right now:
if (!mem_os_commit(mem, KB(64))) { // handle OOM }
memset(mem, 0xAB, KB(64)); // now safe to write

Parameters

ptr	Pointer within a previously reserved block.
size	The amount of physical memory to commit.

Returns

1 (true) if successful, 0 (false) if the OS refused (OOM).

Definition at line 29 of file mem_os.c.

mem_os_decommit()

void mem_os_decommit	(	void *	ptr,
		usize	size )

Decommits physical RAM, returning it to the OS.

The virtual address range remains reserved and can be committed again later without calling mem_os_reserve(). Any access to decommitted memory before recommitting is undefined behavior (access violation / segfault).

Example:

// After a per-level load, return those pages to the OS:
mem_os_decommit(level_buffer, level_size);
// Address space is still reserved — recommit it next level load:
mem_os_commit(level_buffer, next_level_size);

Parameters

ptr	Pointer to the start of the committed range.
size	The amount of memory to decommit.

Definition at line 39 of file mem_os.c.

Here is the caller graph for this function:

mem_os_page_size()

usize mem_os_page_size

(

void

)

Retrieves the operating system's virtual memory page size.

Example:

usize page = mem_os_page_size(); // typically 4096 on Linux/Windows
usize aligned = ALIGN_UP_POW2(my_size, page);

Returns

The page size in bytes (typically 4096 or 65536).

mem_os_release()

void mem_os_release	(	void *	ptr,
		usize	size )

Releases a reserved virtual address block entirely back to the OS.

Frees both the virtual address space and any committed physical RAM. All pointers into the released range become invalid immediately.

Example:

void *mem = mem_os_reserve(GB(1));
mem_os_commit(mem, MB(64));
// ... use mem ...
mem_os_release(mem, GB(1)); // must match the reserved size on POSIX

Parameters

ptr	Pointer returned by mem_os_reserve().
size	Total size originally passed to mem_os_reserve().

Definition at line 50 of file mem_os.c.

Here is the caller graph for this function:

mem_os_reserve()

void * mem_os_reserve

(

usize

size

)

Reserves a contiguous block of virtual address space.

Does not allocate physical RAM. The returned pointer cannot be read or written until mem_os_commit() is called on a sub-range.

Example:

// Reserve 4 GB instantly — no physical cost:
void *base = mem_os_reserve(GB(4));
if (!base) { // handle failure }

Parameters

size	The size of the virtual address block to reserve.

Returns

A pointer to the reserved range, or NULL on failure.

Definition at line 18 of file mem_os.c.

Here is the caller graph for this function: