nlib
|
The heap
library defines a group of mallocheap
-type functions, such as nmalloc
and nfree
, that have C linkages.
More...
Files | |
file | heap.h |
Includes all headers in the heap library. | |
file | NMalloc.h |
File that defines functions including nmalloc and nfree . | |
Classes | |
struct | HeapHash |
Structure that contains a summary of the memory usage status of the heap used by the user application. More... | |
struct | NMallocSettings |
Declares parameters that are initialized by nmalloc . Set by defining nmalloc_get_settings . More... | |
Macros | |
#define | NLIB_REPLACE_MALLOC |
A macro that defines functions like nlib_malloc to use nmalloc . | |
#define | NLIB_REPLACE_MALLOC_NEW |
A macro that defines functions like nlib_malloc to use nmalloc , and also defines new and delete that way. | |
#define | NMALLOC_HEAPOPTION_ENABLE_ENV (0x00000001) |
Enables the setting to be overwritten through the environment variable. | |
#define | NMALLOC_HEAPOPTION_CACHE_DISABLE (0x00000004) |
Disables caching with CachedHeap . More... | |
Typedefs | |
typedef int(* | nmalloc_heapwalk_callback) (void *allocated_ptr, size_t size, void *user_ptr) |
User-defined callback function that is called from nmalloc_walk_allocated_ptrs . More... | |
Enumerations | |
enum | NMallocDumpMode { kNmallocDumpBasic = 0, kNmallocDumpSpans = 1, kNmallocDumpPointers = 2, kNmallocDumpPageSummary = 4, kNmallocDumpAll = kNmallocDumpSpans | kNmallocDumpPointers | kNmallocDumpPageSummary } |
The type of the value that you specify for the second argument when specifying kNmallocQueryDump in the nmalloc_query() function. More... | |
Functions | |
bool | operator== (const HeapHash &rhs, const HeapHash &lhs) |
Returns true if the two compared summaries are equal. | |
bool | operator!= (const HeapHash &rhs, const HeapHash &lhs) |
Returns true if the two compared summaries are not equal. | |
void * | nrealloc (void *ptr, size_t size) |
Changes the memory allocation. Corresponds to the standard C function realloc . More... | |
void * | nmalloc (size_t size) |
Allocates a memory region of the specified size (in bytes). This corresponds to the standard C function, malloc . More... | |
void * | ncalloc (size_t nmemb, size_t size) |
Allocates an array of memory and elements initialized to 0 . More... | |
void * | nmalloc_aligned (size_t size, size_t algn) |
Allocates memory with a specific alignment. More... | |
size_t | nmalloc_size (const void *ptr) |
Returns the amount of memory actually allocated at the ptr parameter. More... | |
void | nfree (void *p) |
Frees a memory region. Corresponds to the standard C function free . More... | |
void | nfree_size (void *p, size_t size) |
Frees a memory region. Using information about memory sizes makes it possible to free memory quickly. More... | |
errno_t | nmalloc_walk_allocated_ptrs (nmalloc_heapwalk_callback func, void *user_ptr) |
The callback function func is called for each region allocated in the heap. More... | |
Variables | |
size_t | HeapHash::alloc_count |
Number of regions allocated by the user application within the heap. | |
size_t | HeapHash::alloc_size |
Total size of the regions allocated by the user application within the heap. | |
size_t | HeapHash::hash |
Hash value of the status of memory allocated by the user application within the heap. | |
void * | NMallocSettings::addr |
Specifies a pointer to the beginning of the region used by nmalloc . | |
size_t | NMallocSettings::size |
Specifies the maximum amount of memory that can be used by nmalloc . You must specify a multiple of 4096 bytes. More... | |
unsigned int | NMallocSettings::heap_option |
Specifies the heap options. The default is 0 . More... | |
nmalloc Initialization and Finalization | |
void | nmalloc_get_settings (NMallocSettings *settings) |
User applications can define this function to control the initialization settings of nmalloc . More... | |
Error-Checking and Debugging Functions | |
errno_t | nmalloc_query (int query,...) |
Gets and operates detailed data on the heap. More... | |
The heap
library defines a group of mallocheap
-type functions, such as nmalloc
and nfree
, that have C linkages.
#define NMALLOC_HEAPOPTION_CACHE_DISABLE (0x00000004) |
Disables caching with CachedHeap
.
NMALLOC_HEAPOPTION_ENABLE_ENV
is specified, a setting in the source code can be overwritten by setting the environment variable NLIB_NMALLOC_DISABLE_TLSCACHE
to a boolean value. int(* nmalloc_heapwalk_callback)(void *allocated_ptr, size_t size, void *user_ptr) |
User-defined callback function that is called from nmalloc_walk_allocated_ptrs
.
[in] | allocated_ptr | Specifies a pointer to the region allocated in the heap. |
[in] | size | Specifies the size of the region. |
[in] | user_ptr | Specifies the user data. |
0 | Indicates that nmalloc_walk_allocated_ptrs will not run continuously. |
1 | Indicates that nmalloc_walk_allocated_ptrs will run continuously. |
0
. enum NMallocDumpMode |
The type of the value that you specify for the second argument when specifying kNmallocQueryDump
in the nmalloc_query()
function.
ncalloc | ( | size_t | nmemb, |
size_t | size | ||
) |
Allocates an array of memory and elements initialized to 0
.
[in] | nmemb | The number of elements. |
[in] | size | The number of bytes for each element. |
NULL
if process fails. nfree | ( | void * | p | ) |
Frees a memory region. Corresponds to the standard C function free
.
[in] | p | Specifies a pointer to the memory block to free. |
nfree_size | ( | void * | p, |
size_t | size | ||
) |
Frees a memory region. Using information about memory sizes makes it possible to free memory quickly.
[in] | p | Specifies a pointer to the memory block to free. |
[in] | size | Indicates the size provided when nmalloc was called. |
sized deallocation
of C++14. Note that this function cannot be used to free memory if nmalloc_aligned
has been used. nmalloc | ( | size_t | size | ) |
Allocates a memory region of the specified size (in bytes). This corresponds to the standard C function, malloc
.
[in] | size | Size of the memory block to be allocated, in bytes. |
NULL
if process fails. nmalloc_aligned | ( | size_t | size, |
size_t | algn | ||
) |
Allocates memory with a specific alignment.
[in] | size | Size of the memory block to be allocated, in bytes. |
[in] | algn | Alignment of the memory block to allocate. |
NULL
if process fails.nmalloc_get_settings | ( | NMallocSettings * | settings | ) |
User applications can define this function to control the initialization settings of nmalloc
.
[out] | settings | nmalloc settings. |
nmalloc
. nmalloc_query | ( | int | query, |
... | |||
) |
Gets and operates detailed data on the heap.
[in] | query | An integer value representing a query. |
[in,out] | ... | Specifies an argument that is dependent on the query value. |
0 | Success. |
EINVAL | The query is incorrect (it is not supported). |
query value | Argument to specify following query | Description of behavior |
---|---|---|
kNmallocQueryDump | int type options (NMallocDumpMode type values). Next, nlib_fd type file descriptor (1 for standard output). | Dumps the heap status. |
kNmallocQueryPageSize | Pointer to size_t | The heap manages memory by page. This gets the size of each page and stores it in the argument. |
>kNmallocQueryAllocatedSize | Pointer to size_t | This gets the total size allocated to users and stores it in the argument. |
kNmallocQueryFreeSize | Pointer to size_t | This gets the total size of regions that have not been allocated and stores it in the argument. |
kNmallocQuerySystemSize | Pointer to size_t | This gets the total size used by the system and stores it in the argument. |
kNmallocQueryMaxAllocatableSize | Pointer to size_t | This gets the maximum size that can be allocated and stores it in the argument. |
kNmallocQueryIsClean | Pointer to int | If a value other than 0 is stored in the argument after the pointer is run, the heap status remains the same as that immediately after it is initialized. This verifies if the heap status is the same as the status obtained immediately after the heap was initialized, including the meta data. Therefore, this may return 0 even if there is no memory leak. By calling after releasing all memory (including releasing cache for each thread with nmalloc_query(kNmallocQueryFinalizeCache) ), the heap status can be closely checked. |
kNmallocQueryHeapHash | Pointer to HeapHash | This looks up the allocation status of the central heap (nn::nlib::heap::CentralHeap ) and calculates a summary. It can be used to investigate memory leaks, among other things. That said, allocatable memory that has been cached in each thread is treated as allocated when the summary is calculated. As a result, it is possible that the summaries may differ even though there is no memory leak. To avoid this issue, either specify NMALLOC_HEAPOPTION_CACHE_DISABLE as the option and initialize the heap, or call nmalloc_query(kNmallocQueryClearCache) from all threads beforehand. |
kNmallocQueryUnifyFreelist | None | Any free lists in the central heap are normally not integrated even after the memory allocated to them has been released. Although this action is effective in terms of execution efficiency, it may encourage memory fragmentation. Executing this command can integrate free lists. |
kNmallocQuerySetColor | A pointer with an area of 4096 bytes or more allocated and a 24-bit integer value | Obtains the 24-bit integer associated with the allocated memory. Returns EINVAL if failed. |
kNmallocQueryGetColor | A pointer with an area of 4096 bytes or more allocated and a 24-bit integer value | Obtains the 24-bit integer associated with the allocated memory. Returns EINVAL if failed. |
kNmallocQuerySetColor | A pointer with an area of 4096 bytes or more allocated and a string | Associates a string of up to 16 bytes, including a null terminating character, with the allocated memory. Returns EINVAL if failed. |
kNmallocQueryGetName | A pointer with an area of 4096 bytes or more allocated, a pointer to the buffer, and the buffer size | Obtains the string associated with the allocated memory. Returns EINVAL if failed. |
kNmallocQueryCheckCache | Pointer to int | This checks the cached free list of allocatable memory. If 0 is stored in the argument after this is run, the data has been broken due to some reason. |
kNmallocQueryClearCache | None | Returns allocatable memory that is cached for a running thread to the central heap. nmalloc has been optimized by caching the memory that can be allocated to each thread. Calling this function explicitly returns any cached allocatable memory to the central heap (nn::nlib::heap::CentralHeap ). |
kNmallocQueryFinalizeCache | None | Returns all thread-specific memory for a running thread including the meta data to the central heap. Called automatically when the thread ends. |
kNmallocQueryFreeSizeNx | Pointer to size_t | Obtains the total size of free physical spaces that have not been allocated and stores that size in the argument. This query can be specified only when the virtual memory allocation function is enabled on the NX platform. If you want to obtain the total size of free spaces within a virtual memory space, call nmalloc_query(kNmallocQueryFreeSize) . |
kNmallocQueryMaxAllocatableSizeNx | Pointer to size_t | Obtains the maximum size that can be physically allocated and stores that size in the argument. This query can be specified only when the virtual memory allocation function is enabled on the NX platform. If you want to obtain the maximum size that can be allocated in a virtual memory space, call nmalloc_query(kNmallocQueryMaxAllocatableSize) . |
nmalloc_size | ( | const void * | ptr | ) |
Returns the amount of memory actually allocated at the ptr parameter.
[in] | ptr | Pointer to a region allocated by a function such as nmalloc . |
nmalloc
._msize
in Windows or malloc_usable_size
in Linux. nmalloc_walk_allocated_ptrs | ( | nmalloc_heapwalk_callback | func, |
void * | user_ptr | ||
) |
The callback function func is called for each region allocated in the heap.
[in] | func | Specifies the callback function. |
[in] | user_ptr | Specifies a pointer for the user. |
0
on success. void * nrealloc | ( | void * | ptr, |
size_t | size | ||
) |
Changes the memory allocation. Corresponds to the standard C function realloc
.
[in] | ptr | Pointer to the heap memory that was allocated using either the nmalloc or nmalloc_aligned function. |
[in] | size | New size of the memory block, in bytes. |
NULL
if process fails. NMallocSettings::heap_option |
Specifies the heap options. The default is 0
.
Value | Result |
---|---|
NMALLOC_HEAPOPTION_ENABLE_ENV | Enables the setting to be overwritten through the environment variable. |
NMALLOC_HEAPOPTION_CACHE_DISABLE | Disables caching with CachedHeap . |
NMallocSettings::size |
Specifies the maximum amount of memory that can be used by nmalloc
. You must specify a multiple of 4096 bytes.
NMALLOC_HEAPOPTION_ENABLE_ENV
is specified, a setting in the source code can be overwritten by configuring the environment variable NLIB_NMALLOC_HEAPSIZE
. However the setting is overwritten only when addr
is not NULL
. © 2012-2017 Nintendo Co., Ltd. All rights reserved.