nlib
NMalloc.h File Reference

File that defines functions including nmalloc and nfree. More...

#include <errno.h>
#include <stddef.h>
#include <stdlib.h>
#include <new>
#include "nn/nlib/Config.h"

Go to the source code of this file.

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

Namespaces

 nn::nlib
 Implements common features and features that are highly platform-dependent. Also refer to nlib Platform APIs. nlib_ns is an alias.
 
 nn::nlib::heap
 Namespace for the heap library. Functions such as nmalloc and nfree are defined in the global namespace.
 

Macros

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

Typedefs

typedef int errno_t
 Indicates with an int-type typedef that a POSIX error value is returned as the return value.
 
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

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...
 
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.
 
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
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...
 
void nmalloc_heaphash (HeapHash *hash)
 Looks up the memory allocation status by the user application and creates a summary. 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

File that defines functions including nmalloc and nfree.

Description
nmalloc and nfree have the following characteristics.
  • Thread cache. Using thread-local storage reduces the need for locks by caching allocatable memory without locking.
  • Low-fragmentation heaps. By grouping packets for each allocation size into memory blocks, packets can be allocated such that the size matches the requested allocation size, which in turn reduces memory fragmentation.
  • Multiple levels of free lists. Maintaining free lists for each size enables high-speed, best-fit allocation.

Definition in file NMalloc.h.