Files CCore/inc/sys/SysMemPage.h CCore/src/sys/SysMemPage.cpp
This part provides primary memory allocation functions. These functions are backed by the OS and can be used to manage memory, accessible by the application.
#ifndef CCore_inc_sys_SysMemPage_h
#define CCore_inc_sys_SysMemPage_h
#include <CCore/inc/Gadget.h>
namespace CCore {
namespace Sys {
/* consts */
const ulen MemPageLen = .... ;
static_assert( (MemPageLen%MaxAlign)==0 ,"CCore::Sys::MemPageLen is not aligned");
/* functions */
void * MemPageAlloc(ulen num_pages) noexcept;
void MemPageFree(void *mem,ulen num_pages) noexcept;
bool MemPageExtend(void *mem,ulen num_pages,ulen plus_num_pages) noexcept;
ulen MemPageShrink(void *mem,ulen num_pages,ulen minus_num_pages) noexcept; // return delta
} // namespace Sys
} // namespace CCore
#endif
MemPageLen is the length of the memory page. All primary memory allocation functions work with memory pages. MemPageLen must be an aligned value.
MemPageAlloc() allocates to the application a continuous range of memory pages. The argument is the number of pages to be allocated. The return value is the address of the first page, or null in case of error. If the num_pages is null, the return value may or may not be null. Such usage is pointless and not recommended. Typically MemPageAlloc() is used to allocate large blocks of memory. If the return value is not null, it means that some range is allocated and must be freed using the function MemPageFree().
The argument mem in the following functions must not be null.
MemPageFree() deallocates a previously allocated range of memory pages. You must provide the address of the first page and the exact number of pages in the range.
MemPageExtend() extends a previously allocated memory page range by the given number of pages. You must provide the address of the first page and the exact number of pages in the range. The last argument is the number of extra pages. The return value is true in case of success. If the OS does not support such kind of operation this function may simply return false.
MemPageShrink() shrinks a previously allocated memory page range by the given number of pages. You must provide the address of the first page and the exact number of pages in the range. The last argument is the number of pages to discard. The return value is the number of discarded from the range pages. It is less or equal than the minus_num_pages and than the num_pages. If the return value is null, none of pages have been discarded. If the final number of pages equals zero, the range itself is still allocated and must be freed using the MemPageFree(). If the OS does not support such kind of operation this function may simply return 0.