nlib
nlib nmalloc functions

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.
 
NLIB_CHECK_RESULT void * nrealloc (void *ptr, size_t size)
 Changes the memory allocation. Corresponds to the standard C function realloc. More...
 
NLIB_CHECK_RESULT void * nmalloc (size_t size)
 Allocates a memory region of the specified size (in bytes). This corresponds to the standard C function, malloc. More...
 
NLIB_CHECK_RESULT void * ncalloc (size_t nmemb, size_t size)
 Allocates an array of memory and elements initialized to 0. More...
 
NLIB_CHECK_RESULT 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...
 

Detailed Description

The heap library defines a group of mallocheap-type functions, such as nmalloc and nfree, that have C linkages.

Macro Definition Documentation

◆ NMALLOC_HEAPOPTION_CACHE_DISABLE

#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 57 of file NMalloc.h.

Typedef Documentation

◆ nmalloc_heapwalk_callback

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_ptrSpecifies a pointer to the region allocated in the heap.
[in]sizeSpecifies the size of the region.
[in]user_ptrSpecifies the user data.
Return values
0Indicates that nmalloc_walk_allocated_ptrs will not run continuously.
1Indicates 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 121 of file NMalloc.h.

Enumeration Type Documentation

◆ NMallocDumpMode

The type of the value that you specify for the second argument when specifying kNmallocQueryDump in the nmalloc_query() function.

Enumerator
kNmallocDumpBasic 

Only displays basic information.

kNmallocDumpSpans 

Displays the usage status for each page.

kNmallocDumpPointers 

Displays the addresses and sizes of all memory allocated by the user application.

kNmallocDumpPageSummary 

Visually displays the overview of the page allocation density in the entire heap. An area of 1 MB is represented with one ASCII character.

kNmallocDumpAll 

Displays all information.

Definition at line 71 of file NMalloc.h.

Function Documentation

◆ ncalloc()

ncalloc ( size_t  nmemb,
size_t  size 
)

Allocates an array of memory and elements initialized to 0.

Parameters
[in]nmembThe number of elements.
[in]sizeThe 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()

nfree ( void *  p)

Frees a memory region. Corresponds to the standard C function free.

Parameters
[in]pSpecifies a pointer to the memory block to free.
Examples:
heap/nmalloc_simple/nmalloc_simple.cpp, heap/object_tracking/object_tracking.cpp, and heap/replace_malloc/replace_malloc.cpp.

◆ nfree_size()

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]pSpecifies a pointer to the memory block to free.
[in]sizeIndicates 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()

nmalloc ( size_t  size)

Allocates a memory region of the specified size (in bytes). This corresponds to the standard C function, malloc.

Parameters
[in]sizeSize of the memory block to be allocated, in bytes.
Returns
If successful, returns a pointer to the allocated memory block. NULL if process fails.
Examples:
heap/nmalloc_leakcheck/nmalloc_leakcheck.cpp, heap/nmalloc_simple/nmalloc_simple.cpp, heap/object_tracking/object_tracking.cpp, and heap/replace_malloc/replace_malloc.cpp.

◆ nmalloc_aligned()

nmalloc_aligned ( size_t  size,
size_t  algn 
)

Allocates memory with a specific alignment.

Parameters
[in]sizeSize of the memory block to be allocated, in bytes.
[in]algnAlignment 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_get_settings()

nmalloc_get_settings ( NMallocSettings settings)

User applications can define this function to control the initialization settings of nmalloc.

Parameters
[out]settingsnmalloc settings.
Description
This function is defined as a weak function by default. User applications can redefine this function to change the initialization settings of nmalloc.
Examples:
heap/nmalloc_leakcheck/nmalloc_leakcheck.cpp, heap/nmalloc_simple/nmalloc_simple.cpp, heap/nmalloc_withstl/nmalloc_withstl.cpp, and heap/replace_malloc/replace_malloc.cpp.

◆ nmalloc_query()

nmalloc_query ( int  query,
  ... 
)

Gets and operates detailed data on the heap.

Parameters
[in]queryAn integer value representing a query.
[in,out]...Specifies an argument that is dependent on the query value.
Return values
0Success.
EINVALThe query is incorrect (it is not supported).
Description
The query argument determines information that can be obtained, behavior, and the argument that should subsequently be specified. The details are summarized in the table below.
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 nlib_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.
Sample code
HeapHash hash;
int intval;
size_t sizeval;
nmalloc_query(kNmallocQueryDump, kNmallocDumpBasic, 1);
nmalloc_query(kNmallocQueryPageSize, &sizeval);
nmalloc_query(kNmallocQueryAllocatedSize, &sizeval);
nmalloc_query(kNmallocQueryFreeSize, &sizeval);
nmalloc_query(kNmallocQuerySystemSize, &sizeval);
nmalloc_query(kNmallocQueryMaxAllocatableSize, &sizeval);
nmalloc_query(kNmallocQueryIsClean, &intval);
nmalloc_query(kNmallocQueryHeapHash, &hash);
nmalloc_query(kNmallocQueryUnifyFreelist);
nmalloc_query(kNmallocQuerySetColor, ptr, 0xFF00FF);
nmalloc_query(kNmallocQueryGetColor, ptr, &intval);
nmalloc_query(kNmallocQuerySetName, ptr, "name of mem");
nmalloc_query(kNmallocQueryGetName, ptr, buf, bufsize);
nmalloc_query(kNmallocQueryCheckCache, &intval);
nmalloc_query(kNmallocQueryClearCache);
nmalloc_query(kNmallocQueryFinalizeCache);
Examples:
heap/nmalloc_leakcheck/nmalloc_leakcheck.cpp, heap/nmalloc_simple/nmalloc_simple.cpp, heap/nmalloc_withstl/nmalloc_withstl.cpp, heap/object_tracking/object_tracking.cpp, and heap/replace_malloc/replace_malloc.cpp.

◆ nmalloc_size()

nmalloc_size ( const void *  ptr)

Returns the amount of memory actually allocated at the ptr parameter.

Parameters
[in]ptrPointer 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.

◆ nmalloc_walk_allocated_ptrs()

nmalloc_walk_allocated_ptrs ( nmalloc_heapwalk_callback  func,
void *  user_ptr 
)

The callback function func is called for each region allocated in the heap.

Parameters
[in]funcSpecifies the callback function.
[in]user_ptrSpecifies a pointer for the user.
Returns
Returns 0 on success.

◆ nrealloc()

void * nrealloc ( void *  ptr,
size_t  size 
)

Changes the memory allocation. Corresponds to the standard C function realloc.

Parameters
[in]ptrPointer to the heap memory that was allocated using either the nmalloc or nmalloc_aligned function.
[in]sizeNew 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.

Variable Documentation

◆ heap_option

NMallocSettings::heap_option

Specifies the heap options. The default is 0.

Description
Value Result
NMALLOC_HEAPOPTION_ENABLE_ENV Enables the setting to be overwritten through the environment variable.
NMALLOC_HEAPOPTION_CACHE_DISABLE Disables caching with CachedHeap.
Examples:
heap/nmalloc_leakcheck/nmalloc_leakcheck.cpp, heap/nmalloc_simple/nmalloc_simple.cpp, heap/nmalloc_withstl/nmalloc_withstl.cpp, and heap/replace_malloc/replace_malloc.cpp.

Definition at line 53 of file NMalloc.h.

◆ size

NMallocSettings::size

Specifies the maximum amount of memory that can be used by nmalloc. You must specify a multiple of 4096 bytes.

Description
If 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.
Examples:
heap/nmalloc_leakcheck/nmalloc_leakcheck.cpp, heap/nmalloc_simple/nmalloc_simple.cpp, heap/nmalloc_withstl/nmalloc_withstl.cpp, and heap/replace_malloc/replace_malloc.cpp.

Definition at line 52 of file NMalloc.h.