pin.h File Reference

Functions for pinning & unpinning memory regions. More...

#include <stddef.h>
#include <stdbool.h>

Go to the source code of this file.

Functions
bool	chic_pin (void *addr, size_t size)
	Pins an object in memory, preventing it from being paged out.
bool	chic_unpin (void *addr, size_t size)
	Unpins an object that was previously pinned in memory using chic_pin, permitting its memory to be paged out.
void *	chic_prefault (void *addr, size_t size)
	Writes zeroes to several locations in a memory range to trigger page faults ahead of time.

Detailed Description

Functions for pinning & unpinning memory regions.

Author

Fawn rubie.nosp@m.fawn.nosp@m.@gmai.nosp@m.l.co.nosp@m.m

Date

2026

Function Documentation

chic_pin()

bool chic_pin	(	void *	addr,
		size_t	size )

Pins an object in memory, preventing it from being paged out.

Parameters

addr	The beginning of the memory range to pin
size	The length of the memory range to pin

Returns

Whether or not the memory range was successfully pinned

Exceptions

EINVAL	if addr is nil or if size is 0
ENOMEM	if any part of the memory range are not valid memory addresses in the calling process, or if the calling process already has too much pinned memory
EAGAIN	if any part of the requested memory range could not be pinned for some reason

See also

POSIX mlock()

Win32 VirtualLock()

chic_prefault()

void * chic_prefault	(	void *	addr,
		size_t	size )

Writes zeroes to several locations in a memory range to trigger page faults ahead of time.

This is to prevent those page faults from happening later in a real-time context. Rather than zeroing the entire buffer, this function tries to only write once per memory page in the range addr to addr + size.

For best results, this memory range should be immediately pinned using chic_pin.

Parameters

addr	The beginning of the memory range to prefault
size	The length of the memory range to prefault

Returns

addr

chic_unpin()

bool chic_unpin	(	void *	addr,
		size_t	size )

Unpins an object that was previously pinned in memory using chic_pin, permitting its memory to be paged out.

Parameters

addr	The beginning of the memory range to unpin
size	The length of the memory range to unpin

Returns

Whether or not the memory range was successfully unpinned

Exceptions

EINVAL	if addr is nil or if size is 0
ENOMEM	if any part of the memory range are not valid memory addresses in the calling process
EAGAIN	if any part of the requested memory range could not be unpinned for some reason

See also

POSIX munlock()

Win32 VirtualUnlock()