Huge Pages

Utilities for allocating huge pages. More...

Classes
class	numapp::HugePageSize
	Describes a huge page size and maintains the invariant that page size is an integral power of 2, compatible with mmap() expectations. More...
class	numapp::HugePageResource
	Polymorphic memory resource allocating huge pages with specified NUMA policy. More...

Enumerations
enum class	numapp::HugePagePreset : std::size_t {   numapp::HugePagePreset::Huge8k = 8 * 1024 , numapp::HugePagePreset::Huge16k = 16 * 1024 , numapp::HugePagePreset::Huge64k = 64 * 1024 , numapp::HugePagePreset::Huge256k = 256 * 1024 ,   numapp::HugePagePreset::Huge1M = 1 * 1024 * 1024 , numapp::HugePagePreset::Huge2M = 2 * 1024 * 1024 , numapp::HugePagePreset::Huge4M = 4 * 1024 * 1024 , numapp::HugePagePreset::Huge16M = 16 * 1024 * 1024 ,   numapp::HugePagePreset::Huge256M = 256 * 1024 * 1024 , numapp::HugePagePreset::Huge1G = 1ul * 1024 * 1024 * 1024 }
	Preset huge page sizes. More...

Functions
auto	numapp::EncodeMmapFlags (HugePageSize page_size) noexcept -> int
	Encodes page size into bit representation expected by mmap().

Allocate and free huge pages
Allocation is similar to Allocate and free but with the additional argument specifying the (huge) page size. Like non-huge allocations the pages are not pre-faulted by the functions so to avoid page fault failurs it is recommended to do that before use. #include <numapp/memory.hpp> void Example() { // Allocate 16MiB from NUMA node 1 in 2MiB pages. auto const size = 16 * 1024 * 1024; auto const page_size = numapp::HugePagePreset::Huge2M; // 1) AllocateHuge will allocate size, rounding up to nearest page_size // multiple void* ptr = numapp::AllocateHuge(size, page_size, numapp::MemPolicy::MakeBindNode(1), numapp::MemPolicyFlag::Strict); // 2) It is particularly important to pre-fault huge-pages as the likelihood // for failure is higher. If page-fault would fail when memory is accessed // the result is a segmentation fault. if (auto ec = numapp::MemLock(ptr, size, numapp::LockFlag::PreFault); ec) { // Page-fault failed; this would have caused a segmentation fault if not // for `numapp::MemLock()`. throw std::system_error(ec, "Page fault failed"); } // 3) FreeHuge will free memory, rounding up to nearest page_size multiple // as required by mmap. numapp::FreeHuge(ptr, size, page_size); } Parameters Parameters [in] size Number of bytes to allocate/free, will be rounded up to multiples of page_size. [in] page_size Page size. [in] policy Memory policy to apply. [in] flags Controls behaviour if memory have to be moved because it was already paged-in due to a numapp.MemLockAll policy. [in] ptr Page-aligned pointer to memory previously allocated with numapp.AllocateHuge(). [out] ec Error code for non-throwing overloads. If there is an out of memory situation the error code std::errc::not_enough_memory is used. Exceptions std::system_error on failure (only applicable to throwing-overloads without std::error_code return value). Returns numapp.AllocateHuge() returns pointer to memory block that is at least size big or nullptr on failure. Related man-page(s): mmap(2) mbind(2)
void *	numapp::AllocateHuge (std::size_t size, HugePageSize page_size, MemPolicy const &policy, MemPolicyFlag flags, std::error_code &ec) noexcept
	Non-throwing version of AllocateHuge()
void *	numapp::AllocateHuge (std::size_t size, HugePageSize page_size, MemPolicy const &policy, MemPolicyFlag flags)
	Throwing version of AllocateHuge()
void	numapp::FreeHuge (void *ptr, std::size_t size, HugePageSize page_size, std::error_code &ec) noexcept
	Free huge pages previously allocated with AllocateHuge.
void *	AllocateHuge (std::size_t size, HugePageSize page_size, MemPolicy const &policy, MemPolicyFlag flags, std::error_code &ec) noexcept
	Non-throwing version of AllocateHuge()
void *	AllocateHuge (std::size_t size, HugePageSize page_size, MemPolicy const &policy, MemPolicyFlag flags)
	Throwing version of AllocateHuge()
void	numapp::FreeHuge (void *ptr, std::size_t size, HugePageSize page_size)
	Throwing version of FreeHuge().

Detailed Description

Utilities for allocating huge pages.

Enumeration Type Documentation

HugePagePreset

enum class numapp::HugePagePreset : std::size_t

strong

Preset huge page sizes.

Commonly supported sizes are

• Huge2M and Huge1G on x86.
• Huge8k, Huge64k, Huge256k, Huge1M, Huge4M, Huge16M, Huge256M on ia64.
• Huge16M on ppc64.

Enumerator
Huge8k	8 KiB page size.
Huge16k	16 KiB page size.
Huge64k	64 kiB page size.
Huge256k	256 kiB page size.
Huge1M	1 MiB page size.
Huge2M	2 MiB page size.
Huge4M	4 MiB page size.
Huge16M	16 MiB page size.
Huge256M	256 MiB page size.
Huge1G	1 GiB page size.

Definition at line 476 of file memory.hpp.

Function Documentation

AllocateHuge() [1/4]

void * numapp::AllocateHuge ( std::size_t size, HugePageSize page_size, MemPolicy const & policy, MemPolicyFlag flags )

nodiscard

Throwing version of AllocateHuge()

See Allocate and free huge pages for details.

Definition at line 193 of file memory.cpp.

AllocateHuge() [2/4]

void * numapp::AllocateHuge ( std::size_t size, HugePageSize page_size, MemPolicy const & policy, MemPolicyFlag flags, std::error_code & ec )

nodiscardnoexcept

Non-throwing version of AllocateHuge()

See Allocate and free huge pages for details.

Definition at line 165 of file memory.cpp.

AllocateHuge() [3/4]

void * AllocateHuge ( std::size_t size, HugePageSize page_size, MemPolicy const & policy, MemPolicyFlag flags )

related

Throwing version of AllocateHuge()

See Allocate and free huge pages for details.

Definition at line 193 of file memory.cpp.

AllocateHuge() [4/4]

void * AllocateHuge ( std::size_t size, HugePageSize page_size, MemPolicy const & policy, MemPolicyFlag flags, std::error_code & ec )

related

Non-throwing version of AllocateHuge()

See Allocate and free huge pages for details.

Definition at line 165 of file memory.cpp.

EncodeMmapFlags()

auto numapp::EncodeMmapFlags ( HugePageSize page_size ) -> int

noexcept

Encodes page size into bit representation expected by mmap().

Returns

Page size encoded as mmap() flags.

Related man-page(s):

• mmap(2)

Definition at line 160 of file memory.cpp.

FreeHuge() [1/2]

void numapp::FreeHuge	(	void *	ptr,
		std::size_t	size,
		HugePageSize	page_size )

Throwing version of FreeHuge().

See Allocate and free huge pages for details.

Exceptions

std::system_error

on errors.

Definition at line 215 of file memory.cpp.

FreeHuge() [2/2]

void numapp::FreeHuge ( void * ptr, std::size_t size, HugePageSize page_size, std::error_code & ec )

noexcept

Free huge pages previously allocated with AllocateHuge.

Note

Behaviour is unspecified if ptr, size and page_size are different than from previous call to AllocateHuge().

page_size is needed because munmap requires that sz in munmap(ptr, sz) is a multiple of page size, which is not the case for system pages.

See Allocate and free huge pages for details.

Definition at line 205 of file memory.cpp.