nlib
nlib nmalloc functions

heapライブラリ内にはCリンケージを持つnmalloc/nfree等のmalloc関連関数群が定義されています。 [詳解]

ファイル

ファイル  heap.h
 ヒープライブラリのヘッダを全てインクルードします。
 
ファイル  NMalloc.h
 nmalloc/nfree等が宣言されているファイルです。
 

クラス

struct  HeapHash
 ユーザーが利用しているヒープ内のメモリの利用状況のサマリが記述される構造体です。 [詳解]
 
struct  NMallocSettings
 nmallocの初期設定を行うパラメータを記述します。nmalloc_get_settings()を定義して設定します。 [詳解]
 

マクロ定義

#define NLIB_REPLACE_MALLOC
 nlib_malloc()等をnmallocを利用するように定義するマクロです。
 
#define NLIB_REPLACE_MALLOC_NEW
 nlib_malloc()等をnmallocを利用するように定義し、new/deleteもそのように定義するマクロです。
 
#define NMALLOC_HEAPOPTION_ENABLE_ENV   (0x00000001)
 環境変数による設定の上書きを有効にします。
 
#define NMALLOC_HEAPOPTION_CACHE_DISABLE   (0x00000004)
 CachedHeapによるキャッシングを無効にします。 [詳解]
 

型定義

typedef int(* nmalloc_heapwalk_callback) (void *allocated_ptr, size_t size, void *user_ptr)
 nmalloc_walk_allocated_ptrs()から呼び出されるユーザー定義のコールバック関数です。 [詳解]
 

列挙型

enum  NMallocDumpMode {
  NMALLOC_DUMP_BASIC = 0,
  NMALLOC_DUMP_SPANS = 1,
  NMALLOC_DUMP_POINTERS = 2,
  NMALLOC_DUMP_PAGESUMMARY = 4,
  NMALLOC_DUMP_ALL = NMALLOC_DUMP_SPANS | NMALLOC_DUMP_POINTERS | NMALLOC_DUMP_PAGESUMMARY
}
 nmalloc_query()関数でNMALLOC_QUERY_DUMPを指定した場合に第2引数に指定する値の型です。 [詳解]
 

関数

bool operator== (const HeapHash &rhs, const HeapHash &lhs)
 2つのサマリを比較して等価ならば、trueを返します。
 
bool operator!= (const HeapHash &rhs, const HeapHash &lhs)
 2つのサマリを比較して等価でなければ、trueを返します。
 
NLIB_CHECK_RESULT void * nrealloc (void *ptr, size_t size)
 メモリの割り当てを変更します。realloc()C標準関数に相当します。 [詳解]
 
NLIB_CHECK_RESULT void * nmalloc (size_t size)
 指定バイト分のメモリ領域を確保します。malloc()C標準関数に相当します。 [詳解]
 
NLIB_CHECK_RESULT void * ncalloc (size_t nmemb, size_t size)
 0に初期化される要素とメモリの配列を割り当てます。 [詳解]
 
NLIB_CHECK_RESULT void * nmalloc_aligned (size_t size, size_t algn)
 アライメントを指定してメモリ領域を確保します。 [詳解]
 
size_t nmalloc_size (const void *ptr)
 ptrに実際に割り当てられたメモリ量を返します。 [詳解]
 
void nfree (void *p)
 メモリ領域を解放します。free()C標準関数に相当します。 [詳解]
 
void nfree_size (void *p, size_t size)
 メモリ領域を解放します。メモリのサイズ情報を利用することで高速にメモリを解放できることがあります。 [詳解]
 
errno_t nmalloc_walk_allocated_ptrs (nmalloc_heapwalk_callback func, void *user_ptr)
 ヒープにアロケートされた領域1つずつに対してコールバック関数func を呼び出します。 [詳解]
 

変数

size_t HeapHash::alloc_count
 ヒープ内でユーザーによってアロケートされた領域の数です。
 
size_t HeapHash::alloc_size
 ヒープ内でユーザーによってアロケートされた領域のサイズの合計です。
 
size_t HeapHash::hash
 ヒープ内のユーザーによるメモリ確保の状況をハッシュ値にしたものです。
 
void * NMallocSettings::addr
 nmallocが利用する領域の先頭へのポインタを指定します。
 
size_t NMallocSettings::size
 nmallocが利用する最大のメモリサイズを指定します。4096バイトの倍数を指定する必要があります。 [詳解]
 
unsigned int NMallocSettings::heap_option
 ヒープオプションを指定します。デフォルトは0です。 [詳解]
 

nmallocの初期化と終了

void nmalloc_get_settings (NMallocSettings *settings)
 ユーザーがこの関数を定義することでnmallocの初期化設定をコントロールすることができます。 [詳解]
 

エラーチェック及びデバック用関数

errno_t nmalloc_query (int query,...)
 ヒープに関する詳細なデータの取得や操作を行います。 [詳解]
 

詳解

heapライブラリ内にはCリンケージを持つnmalloc/nfree等のmalloc関連関数群が定義されています。

マクロ定義詳解

§ NMALLOC_HEAPOPTION_CACHE_DISABLE

#define NMALLOC_HEAPOPTION_CACHE_DISABLE   (0x00000004)

CachedHeapによるキャッシングを無効にします。

説明
NMALLOC_HEAPOPTION_ENABLE_ENVが指定されている場合は、環境変数NLIB_NMALLOC_DISABLE_TLSCACHEに真偽値を設定することで、ソースコード上の設定を上書きすることが可能です。
各種例:
heap/nmalloc_leakcheck/nmalloc_leakcheck.cpp.

NMalloc.h44 行目に定義があります。

型定義詳解

§ nmalloc_heapwalk_callback

int(* nmalloc_heapwalk_callback)(void *allocated_ptr, size_t size, void *user_ptr)

nmalloc_walk_allocated_ptrs()から呼び出されるユーザー定義のコールバック関数です。

引数
[in]allocated_ptrヒープにアロケートされた領域へのポインタ
[in]size領域のサイズ
[in]user_ptrユーザーデータ
戻り値
0nmalloc_walk_allocated_ptrs()の継続実行を行わない場合
1nmalloc_walk_allocated_ptrs()の継続実行を行う場合
説明
コールバック内でメモリの確保や解放を行う場合は、0を返すようにしてください。

NMalloc.h86 行目に定義があります。

列挙型詳解

§ NMallocDumpMode

nmalloc_query()関数でNMALLOC_QUERY_DUMPを指定した場合に第2引数に指定する値の型です。

列挙値
NMALLOC_DUMP_BASIC 

基本的な情報のみを表示します。

NMALLOC_DUMP_SPANS 

ページ単位の利用状況を表示します。

NMALLOC_DUMP_POINTERS 

ユーザーによって確保されている全てのメモリのアドレスとサイズを表示します。

NMALLOC_DUMP_PAGESUMMARY 

ヒープ全体のページの割当密度の概要を視覚的に表示します。1MBを1つのASCIIキャラクタで表現しています。

NMALLOC_DUMP_ALL 

情報を全て表示します。

NMalloc.h58 行目に定義があります。

関数詳解

§ ncalloc()

ncalloc ( size_t  nmemb,
size_t  size 
)

0に初期化される要素とメモリの配列を割り当てます。

引数
[in]nmemb要素の数
[in]size各要素のバイト数
戻り値
成功した場合は確保したメモリブロックを指すポインタ。失敗した場合はNULL
各種例:
heap/replace_malloc/replace_malloc.cpp.

§ nfree()

nfree ( void *  p)

メモリ領域を解放します。free()C標準関数に相当します。

引数
[in]p解放するメモリブロックのポインタ
各種例:
heap/nmalloc_simple/nmalloc_simple.cpp, heap/object_tracking/object_tracking.cpp, heap/replace_malloc/replace_malloc.cpp.

§ nfree_size()

nfree_size ( void *  p,
size_t  size 
)

メモリ領域を解放します。メモリのサイズ情報を利用することで高速にメモリを解放できることがあります。

引数
[in]p解放するメモリブロックのポインタ
[in]sizenmalloc()の呼び出しの際に与えたサイズ
説明
C++14のsized deallocationに対応するための関数です。 nmalloc_aligned()を利用した場合にこの関数で解放することはできないことに注意してください。
各種例:
heap/replace_malloc/replace_malloc.cpp.

§ nmalloc()

nmalloc ( size_t  size)

指定バイト分のメモリ領域を確保します。malloc()C標準関数に相当します。

引数
[in]size確保したいメモリのバイトサイズ
戻り値
成功した場合は確保したメモリブロックを指すポインタ。失敗した場合はNULL
各種例:
heap/nmalloc_leakcheck/nmalloc_leakcheck.cpp, heap/nmalloc_simple/nmalloc_simple.cpp, heap/object_tracking/object_tracking.cpp, heap/replace_malloc/replace_malloc.cpp.

§ nmalloc_aligned()

nmalloc_aligned ( size_t  size,
size_t  algn 
)

アライメントを指定してメモリ領域を確保します。

引数
[in]size確保したいメモリのバイトサイズ
[in]algn確保したいメモリのアライメント
戻り値
成功した場合は確保したメモリブロックを指すポインタ。失敗した場合はNULL
説明
algn は8以上で2のべき乗となる値を指定する必要があります。
各種例:
heap/replace_malloc/replace_malloc.cpp.

§ nmalloc_get_settings()

nmalloc_get_settings ( NMallocSettings settings)

ユーザーがこの関数を定義することでnmallocの初期化設定をコントロールすることができます。

引数
[out]settingsnmallocの設定
説明
この関数はデフォルトがweak関数として定義されていて、ユーザーが再定義することでnmallocの初期化設定を変更することができるようになります。
各種例:
heap/nmalloc_leakcheck/nmalloc_leakcheck.cpp, heap/nmalloc_simple/nmalloc_simple.cpp, heap/nmalloc_withstl/nmalloc_withstl.cpp, heap/replace_malloc/replace_malloc.cpp.

§ nmalloc_query()

nmalloc_query ( int  query,
  ... 
)

ヒープに関する詳細なデータの取得や操作を行います。

引数
[in]queryクエリを表す整数値です。
[in,out]...queryの値に依存する引数を指定します。
戻り値
0成功しました。
EINVALクエリが正しくない場合(サポートされていない場合)
説明
query引数によって、得られる情報、動作、及び以後に指定すべき引数が決まります。 詳細を以下のテーブルにまとめます。
queryの値 queryの後に指定する引数 動作の説明
NMALLOC_QUERY_DUMP int型のオプション(NMallocDumpMode型の値)。
その次にnlib_fd型のファイルディスクリプタ(1で標準出力)。
ヒープの状況をダンプします。
NMALLOC_QUERY_PAGE_SIZE size_tへのポインタ ヒープはページ単位でメモリを管理していますが、そのページのサイズを取得して引数に格納します。
NMALLOC_QUERY_ALLOCATED_SIZE size_tへのポインタ ユーザーによってアロケートされているサイズの合計を取得して引数に格納します。
NMALLOC_QUERY_FREE_SIZE size_tへのポインタ アロケートされていない領域のサイズの合計を取得して引数に格納します。
NMALLOC_QUERY_SYSTEM_SIZE size_tへのポインタ システムによって利用されているサイズの合計を取得して引数に格納します。
NMALLOC_QUERY_MAX_ALLOCATABLE_SIZE size_tへのポインタ アロケート可能な最大サイズを取得して引数に格納します。
NMALLOC_QUERY_IS_CLEAN intへのポインタ 実行後に引数に0以外が格納されている場合は、ヒープは初期化直後と同じ状態です。 ヒープの状態が初期化直後と同じかどうかをメタデータも含めて確認します。 従ってメモリリークしていなくても0を返す場合があります。 全てのメモリの解放後(nmalloc_query(NMALLOC_QUERY_FINALIZE_CACHE)によるスレッド毎のキャッシュの解放も含む)に呼び出すことで、ヒープの状態を厳密にチェックすることができます。
NMALLOC_QUERY_HEAP_HASH HeapHashへのポインタ 中央ヒープ(nn::nlib::heap::CentralHeap)の割り当て状況を調査し、サマリを計算します。 メモリリークの調査等に利用することが可能です。 ただし、各スレッドにキャッシュされている割り当て可能なメモリは確保されているものとしてサマリが計算されます。 従って、メモリリークしていないのにサマリが異なる、といった状況がありえます。 これを避けるにはオプションにNMALLOC_HEAPOPTION_CACHE_DISABLEを指定してヒープを初期化するか、事前にnlib_query(NMALLOC_QUERY_CLEAR_CACHE)を全てのスレッドで呼び出しておきます。
NMALLOC_QUERY_UNIFY_FREELIST なし 中央ヒープ内のフリーリストは通常はメモリの解放後も統合されません。 これは実行効率的にはよいのですが、メモリの断片化を悪化させる可能性があります。 このコマンドを実行することで、フリーリストを統合することができます。
NMALLOC_QUERY_SET_COLOR 4096バイト以上のサイズでアロケートされたポインタと24bitの整数値 アロケートされたメモリに24bitの整数値を関連付けます。 失敗した場合にはEINVALを返します。
NMALLOC_QUERY_GET_COLOR 4096バイト以上のサイズでアロケートされたポインタと24bitの整数値 アロケートされたメモリに関連付けられた24bitの整数値を取得します。 失敗した場合にはEINVALを返します。
NMALLOC_QUERY_SET_COLOR 4096バイト以上のサイズでアロケートされたポインタと文字列 アロケートされたメモリに16バイトまで(終端のヌル文字を含む)の文字列を関連付けます。 失敗した場合にはEINVALを返します。
NMALLOC_QUERY_GET_NAME 4096バイト以上のサイズでアロケートされたポインタとバッファへのポインタとバッファサイズ アロケートされたメモリに関連付けられた文字列を取得します。 失敗した場合にはEINVALを返します。
NMALLOC_QUERY_CHECK_CACHE intへのポインタ キャッシュされている割当可能なメモリのフリーリストをチェックします。 実行後に引数に0が格納されていた場合は何らかの原因でデータが壊れています。
NMALLOC_QUERY_CLEAR_CACHE なし 実行中のスレッドにキャッシュされている割り当て可能なメモリを中央ヒープに返します。 nmallocは各スレッドに割り当て可能なメモリをキャッシュすることで高速化を行なっていますが、この関数を呼び出すことでキャッシュされている割り当て可能メモリを中央ヒープ(nn::nlib::heap::CentralHeap)に明示的に返却します。
NMALLOC_QUERY_FINALIZE_CACHE なし 実行中のスレッド固有のメモリをメタデータを含めて全て中央ヒープに返却します。 スレッドが終了するときに自動的に呼び出されます。
コード例
HeapHash hash;
int intval;
size_t sizeval;
nmalloc_query(NMALLOC_QUERY_DUMP, NMALLOC_DUMP_BASIC, 1);
nmalloc_query(NMALLOC_QUERY_PAGE_SIZE, &sizeval);
nmalloc_query(NMALLOC_QUERY_ALLOCATED_SIZE, &sizeval);
nmalloc_query(NMALLOC_QUERY_FREE_SIZE, &sizeval);
nmalloc_query(NMALLOC_QUERY_SYSTEM_SIZE, &sizeval);
nmalloc_query(NMALLOC_QUERY_MAX_ALLOCATABLE_SIZE, &sizeval);
nmalloc_query(NMALLOC_QUERY_IS_CLEAN, &intval);
nmalloc_query(NMALLOC_QUERY_HEAP_HASH, &hash);
nmalloc_query(NMALLOC_QUERY_UNIFY_FREELIST);
nmalloc_query(NMALLOC_QUERY_SET_COLOR, ptr, 0xFF00FF);
nmalloc_query(NMALLOC_QUERY_GET_COLOR, ptr, &intval);
nmalloc_query(NMALLOC_QUERY_SET_NAME, ptr, "name of mem");
nmalloc_query(NMALLOC_QUERY_GET_NAME, ptr, buf, bufsize);
nmalloc_query(NMALLOC_QUERY_CHECK_CACHE, &intval);
nmalloc_query(NMALLOC_QUERY_CLEAR_CACHE);
nmalloc_query(NMALLOC_QUERY_FINALIZE_CACHE);
各種例:
heap/nmalloc_leakcheck/nmalloc_leakcheck.cpp, heap/nmalloc_simple/nmalloc_simple.cpp, heap/nmalloc_withstl/nmalloc_withstl.cpp, heap/object_tracking/object_tracking.cpp, heap/replace_malloc/replace_malloc.cpp.

§ nmalloc_size()

nmalloc_size ( const void *  ptr)

ptrに実際に割り当てられたメモリ量を返します。

引数
[in]ptrnmalloc等で割り当てられた領域へのポインタ
戻り値
実際にnmalloc等が割り当てたメモリ量
説明
Windowsにおける_msize()関数や、Linuxにおけるmalloc_usable_size()と同等の機能です。

§ nmalloc_walk_allocated_ptrs()

nmalloc_walk_allocated_ptrs ( nmalloc_heapwalk_callback  func,
void *  user_ptr 
)

ヒープにアロケートされた領域1つずつに対してコールバック関数func を呼び出します。

引数
[in]funcコールバック関数
[in]user_ptrユーザー用ポインタ
戻り値
0ならば成功

§ nrealloc()

void * nrealloc ( void *  ptr,
size_t  size 
)

メモリの割り当てを変更します。realloc()C標準関数に相当します。

引数
[in]ptrnmalloc(), nmalloc_aligned()関数を用いて確保したヒープメモリへのポインタ。
[in]size変更したいメモリのバイトサイズ
戻り値
成功した場合は再確保したメモリブロックを指すポインタ。失敗した場合はNULL
各種例:
heap/nmalloc_simple/nmalloc_simple.cpp, heap/replace_malloc/replace_malloc.cpp.

変数詳解

§ heap_option

NMallocSettings::heap_option

ヒープオプションを指定します。デフォルトは0です。

説明
効果
NMALLOC_HEAPOPTION_ENABLE_ENV 環境変数による設定の上書きを有効にします。
NMALLOC_HEAPOPTION_CACHE_DISABLE CachedHeapによるキャッシングを無効にします。
各種例:
heap/nmalloc_leakcheck/nmalloc_leakcheck.cpp, heap/nmalloc_simple/nmalloc_simple.cpp, heap/nmalloc_withstl/nmalloc_withstl.cpp, heap/replace_malloc/replace_malloc.cpp.

NMalloc.h40 行目に定義があります。

§ size

NMallocSettings::size

nmallocが利用する最大のメモリサイズを指定します。4096バイトの倍数を指定する必要があります。

説明
NMALLOC_HEAPOPTION_ENABLE_ENVが指定されている場合は、環境変数NLIB_NMALLOC_HEAPSIZEを設定することにより、ソースコード上の設定を上書きすることが可能です。 ただし、addrNULLでない場合のみ上書きされます。
各種例:
heap/nmalloc_leakcheck/nmalloc_leakcheck.cpp, heap/nmalloc_simple/nmalloc_simple.cpp, heap/nmalloc_withstl/nmalloc_withstl.cpp, heap/replace_malloc/replace_malloc.cpp.

NMalloc.h39 行目に定義があります。