The heap
library defines a group of mallocheap
-type functions, such as nmalloc
and nfree
, that have C linkages.
More...
|
file | heap.h |
| Includes all headers in the heap library.
|
|
file | NMalloc.h |
| File that defines functions including nmalloc and nfree .
|
|
|
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...
|
|
|
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...
|
|
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
.
- Description
- If
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.
- Examples:
- heap/nmalloc_leakcheck/nmalloc_leakcheck.cpp.
Definition at line 44 of file NMalloc.h.
#define NMALLOC_HEAPOPTION_CHECK_0 (0x00000000) |
Runs at maximum efficiency using the default settings.
- Description
- If
NMALLOC_HEAPOPTION_ENABLE_ENV
is specified, a setting in the source code can be overwritten by setting the environment variable NLIB_NMALLOC_MODE
to 0
.
Definition at line 45 of file NMalloc.h.
#define NMALLOC_HEAPOPTION_CHECK_1 (0x00000008) |
Makes it possible to set two 16-bit metadata values. Detects data corruption at the beginning portion of memory.
- Description
- If
NMALLOC_HEAPOPTION_ENABLE_ENV
is specified, a setting in the source code can be overwritten by setting the environment variable NLIB_NMALLOC_MODE
to 1
.
- Examples:
- heap/object_tracking/object_tracking.cpp.
Definition at line 46 of file NMalloc.h.
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
.
- Parameters
-
[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. |
- Return values
-
0 | Indicates that nmalloc_walk_allocated_ptrs will not run continuously. |
1 | Indicates that nmalloc_walk_allocated_ptrs will run continuously. |
- Description
- If you are going to allocate and free memory within the callback, make sure to return
0
.
Definition at line 67 of file NMalloc.h.
Type of the argument to pass to nmalloc_dumpex
.
Enumerator |
---|
NMALLOC_DUMP_BASIC |
Only displays basic information.
|
NMALLOC_DUMP_SPANS |
Displays the usage status for each page.
|
NMALLOC_DUMP_POINTERS |
Displays the addresses and sizes of all memory allocated by the user application.
|
NMALLOC_DUMP_ALL |
Displays all information.
|
Definition at line 60 of file NMalloc.h.
ncalloc |
( |
size_t |
nmemb, |
|
|
size_t |
size |
|
) |
| |
Allocates an array of memory and elements initialized to 0
.
- Parameters
-
[in] | nmemb | The number of elements. |
[in] | size | The number of bytes for each element. |
- Returns
- If successful, returns a pointer to the allocated memory block.
NULL
if process fails.
- Examples:
- heap/replace_malloc/replace_malloc.cpp.
nfree_size |
( |
void * |
p, |
|
|
size_t |
size |
|
) |
| |
Frees a memory region. Using information about memory sizes makes it possible to free memory quickly.
- Parameters
-
[in] | p | Specifies a pointer to the memory block to free. |
[in] | size | Indicates the size provided when nmalloc was called. |
- Description
- This function is for supporting
sized deallocation
of C++14. Note that this function cannot be used to free memory if nmalloc_aligned
has been used.
- Examples:
- heap/replace_malloc/replace_malloc.cpp.
nmalloc_aligned |
( |
size_t |
size, |
|
|
size_t |
algn |
|
) |
| |
Allocates memory with a specific alignment.
- Parameters
-
[in] | size | Size of the memory block to be allocated, in bytes. |
[in] | algn | Alignment of the memory block to allocate. |
- Returns
- If successful, returns a pointer to the allocated memory block.
NULL
if process fails.
- Description
- algn must be a power of two that is equal to or larger than 8.
- Examples:
- heap/replace_malloc/replace_malloc.cpp.
nmalloc_clear_tls |
( |
void |
| ) |
|
Dumps the basic heap status.
- Description
- Equivalent to
nmalloc_dumpex(NMALLOC_DUMP_BASIC)
.
Dumps the heap status.
- Parameters
-
[in] | mode | Specifies the display options. |
[in] | fd | Specifies the file descriptor to display. |
- Description
- TODO(nishida_kenji): Write a detailed description after the tag specifications have been finalized.
nmalloc_finalize_tls |
( |
void |
| ) |
|
Returns all thread-specific memory for a running thread to the central heap. You must call this when ending a thread.
- Description
- In addition to
nmalloc_clear_tls
, the data region used to manage the cache is also be returned to the CentralHeap
.
- Examples:
- heap/nmalloc_simple/nmalloc_simple.cpp.
nmalloc_getmark |
( |
const void * |
ptr, |
|
|
uint16_t * |
mark1, |
|
|
uint16_t * |
mark2 |
|
) |
| |
Gets data that was added to allocated memory.
- Parameters
-
[in] | ptr | Specifies a pointer to an allocated object. |
[out] | mark1 | Pointer to the location storing the first piece of 16-bit additional data. Can specify NULL . |
[out] | mark2 | Pointer to the location storing the second piece of 16-bit additional data. Can specify NULL . |
- Returns
- Returns
0
on success.
- Description
- This runs
CachedHeap::GetMark
behind the scenes. For more information, see CachedHeap::GetMark
.
nmalloc_getobjptr |
( |
void * |
raw_ptr | ) |
|
Transforms the pointer passed to nmalloc_heapwalk_callback
into an object pointer.
- Parameters
-
[in] | raw_ptr | Specifies the pointer passed to nmalloc_heapwalk_callback . |
- Returns
- Returns an object pointer.
- Description
- This runs
CachedHeap::GetObjPtr
behind the scenes. For more information, see CachedHeap::GetObjPtr
.
Looks up the memory allocation status by the user application and creates a summary.
- Parameters
-
[in] | hash | Structure to use to store the summary. |
- Description
- 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 an option and initialize the heap, or call nmalloc_clear_tls
from all threads beforehand.
- Examples:
- heap/nmalloc_leakcheck/nmalloc_leakcheck.cpp.
Checks whether the heap status is the same as it was immediately following initialization.
- Returns
- Returns
true
if the same as the heap status immediately following initialization.
- Description
- By calling after releasing all memory (including releasing cache for each thread with
nmalloc_finalize_tls
), the heap status can be closely checked. It checks whether the current heap status is the same as the status immediately after initialization, including metadata. As a result, it may fail even if there is no memory leak.
- Examples:
- heap/nmalloc_simple/nmalloc_simple.cpp.
nmalloc_setmark1 |
( |
void * |
p, |
|
|
uint16_t |
mark1 |
|
) |
| |
Adds data to allocated memory.
- Parameters
-
[in] | p | Specifies a pointer to an allocated object. |
[in] | mark1 | Specifies the first piece of 16-bit additional data. |
- Returns
- Returns
0
on success.
- Description
- This runs
CachedHeap::SetMark1
behind the scenes. For details, see CachedHeap::SetMark1
.
nmalloc_setmark2 |
( |
void * |
p, |
|
|
uint16_t |
mark2 |
|
) |
| |
Adds data to allocated memory.
- Parameters
-
[in] | p | Specifies a pointer to an allocated object. |
[in] | mark2 | Specifies the second piece of 16-bit additional data. |
- Returns
- Returns
0
on success.
- Description
- This runs
CachedHeap::SetMark2
behind the scenes. For more information, see CachedHeap::SetMark2
.
nmalloc_size |
( |
const void * |
ptr | ) |
|
Returns the amount of memory actually allocated at the ptr parameter.
- Parameters
-
[in] | ptr | Pointer to a region allocated by a function such as nmalloc . |
- Returns
- Returns the amount of memory actually allocated by a function such as
nmalloc
.
- Description
- This feature is equivalent to
_msize
in Windows or malloc_usable_size
in Linux.
The callback function func is called for each region allocated in the heap.
- Parameters
-
[in] | func | Specifies the callback function. |
[in] | user_ptr | Specifies a pointer for the user. |
- Returns
- Returns
0
on success.
void * nrealloc |
( |
void * |
ptr, |
|
|
size_t |
size |
|
) |
| |
Changes the memory allocation. Corresponds to the standard C function realloc
.
- Parameters
-
[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. |
- Returns
- If successful, returns a pointer to the reallocated memory block.
NULL
if process fails.
- Examples:
- heap/nmalloc_simple/nmalloc_simple.cpp, and heap/replace_malloc/replace_malloc.cpp.
NMallocSettings::heap_option |