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...
 
#define NMALLOC_HEAPOPTION_CHECK_0   (0x00000000)
 Runs at maximum efficiency using the default settings. More...
 
#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. 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 {
  NMALLOC_DUMP_BASIC = 0,
  NMALLOC_DUMP_SPANS = 1,
  NMALLOC_DUMP_POINTERS = 2,
  NMALLOC_DUMP_ALL = NMALLOC_DUMP_SPANS | NMALLOC_DUMP_POINTERS
}
 Type of the argument to pass to nmalloc_dumpex. 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 nmalloc_clear_tls (void)
 Returns allocatable memory that is cached for a running thread to the CentralHeap. More...
 
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...
 
void 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. More...
 

Error-Checking and Debugging Functions

void nmalloc_heaphash (HeapHash *hash)
 Looks up the memory allocation status by the user application and creates a summary. More...
 
int nmalloc_isclean (void)
 Checks whether the heap status is the same as it was immediately following initialization. More...
 
void nmalloc_dump (void)
 Dumps the basic heap status. More...
 
void nmalloc_dumpex (NMallocDumpMode mode)
 Dumps the heap status. More...
 
void nmalloc_dumpex2 (NMallocDumpMode mode, nlib_fd fd)
 Dumps the heap status. More...
 

Functions for Adding Metadata to Allocated Memory

Some NMallocSettings settings allow user applications to add metadata.

errno_t nmalloc_setmark1 (void *p, uint16_t mark1)
 Adds data to allocated memory. More...
 
errno_t nmalloc_setmark2 (void *p, uint16_t mark2)
 Adds data to allocated memory. More...
 
errno_t nmalloc_getmark (const void *ptr, uint16_t *mark1, uint16_t *mark2)
 Gets data that was added to allocated memory. More...
 
void * nmalloc_getobjptr (void *raw_ptr)
 Transforms the pointer passed to nmalloc_heapwalk_callback into an object pointer. 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

#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.

Typedef Documentation

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

Enumeration Type Documentation

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.

Function Documentation

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 ( 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, and 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]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 ( 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, and heap/replace_malloc/replace_malloc.cpp.
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_clear_tls ( void  )

Returns allocatable memory that is cached for a running thread to the CentralHeap.

Description
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 CentralHeap.
Examples:
heap/nmalloc_withstl/nmalloc_withstl.cpp, and heap/replace_malloc/replace_malloc.cpp.
nmalloc_dump ( void  )

Dumps the basic heap status.

Description
Equivalent to nmalloc_dumpex(NMALLOC_DUMP_BASIC).
void nmalloc_dumpex ( NMallocDumpMode  mode)

Dumps the heap status.

Parameters
[in]modeSpecifies the display options.
Description
TODO(nishida_kenji): Write a detailed description after the tag specifications have been finalized.
Examples:
heap/nmalloc_simple/nmalloc_simple.cpp, heap/nmalloc_withstl/nmalloc_withstl.cpp, and heap/replace_malloc/replace_malloc.cpp.
void nmalloc_dumpex2 ( NMallocDumpMode  mode,
nlib_fd  fd 
)

Dumps the heap status.

Parameters
[in]modeSpecifies the display options.
[in]fdSpecifies 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_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_getmark ( const void *  ptr,
uint16_t *  mark1,
uint16_t *  mark2 
)

Gets data that was added to allocated memory.

Parameters
[in]ptrSpecifies a pointer to an allocated object.
[out]mark1Pointer to the location storing the first piece of 16-bit additional data. Can specify NULL.
[out]mark2Pointer 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_ptrSpecifies 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.
nmalloc_heaphash ( HeapHash hash)

Looks up the memory allocation status by the user application and creates a summary.

Parameters
[in]hashStructure 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.
nmalloc_isclean ( void  )

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]pSpecifies a pointer to an allocated object.
[in]mark1Specifies 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]pSpecifies a pointer to an allocated object.
[in]mark2Specifies 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]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_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.
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

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.
NMALLOC_HEAPOPTION_CHECK_0 Runs at maximum efficiency using the default settings.
NMALLOC_HEAPOPTION_CHECK_1 Makes it possible to set two 16-bit metadata values. Detects data corruption at the beginning portion of memory.
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 40 of file NMalloc.h.

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