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によるキャッシングを無効にします。 [詳解]
 
#define NMALLOC_HEAPOPTION_CHECK_0   (0x00000000)
 デフォルト設定で最も効率よく動作します。 [詳解]
 
#define NMALLOC_HEAPOPTION_CHECK_1   (0x00000008)
 16bitのメタデータを2つ設定可能にします。メモリの先頭部分のデータ破壊を検出します。 [詳解]
 

型定義

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_ALL = NMALLOC_DUMP_SPANS | NMALLOC_DUMP_POINTERS
}
 nmalloc_dumpex()関数に渡す引数の型です。 [詳解]
 

関数

bool operator== (const HeapHash &rhs, const HeapHash &lhs)
 2つのサマリを比較して等価ならば、trueを返します。
 
bool operator!= (const HeapHash &rhs, const HeapHash &lhs)
 2つのサマリを比較して等価でなければ、trueを返します。
 
void nmalloc_clear_tls (void)
 実行中のスレッドにキャッシュされている割り当て可能なメモリを中央ヒープに返します。 [詳解]
 
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の初期化設定をコントロールすることができます。 [詳解]
 
void nmalloc_finalize_tls (void)
 実行中のスレッド固有のメモリを全て中央ヒープに返却します。スレッドを終了させるときに呼び出す必要があります。 [詳解]
 

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

void nmalloc_heaphash (HeapHash *hash)
 ユーザーによるメモリ確保状況を調べてサマリを作成します。 [詳解]
 
int nmalloc_isclean (void)
 ヒープの状態が初期化直後と同じかどうか確認します。 [詳解]
 
void nmalloc_dump (void)
 ヒープの基本的な状況をダンプします。 [詳解]
 
void nmalloc_dumpex (NMallocDumpMode mode)
 ヒープの状況をダンプします。 [詳解]
 
void nmalloc_dumpex2 (NMallocDumpMode mode, nlib_fd fd)
 ヒープの状況をダンプします。 [詳解]
 

アロケートされたメモリへメタデータを付加する関数

NMallocSettingsの設定によっては、ユーザーがメタデータを付加することができます。

errno_t nmalloc_setmark1 (void *p, uint16_t mark1)
 アロケートされたメモリに情報を付加します。 [詳解]
 
errno_t nmalloc_setmark2 (void *p, uint16_t mark2)
 アロケートされたメモリに情報を付加します。 [詳解]
 
errno_t nmalloc_getmark (const void *ptr, uint16_t *mark1, uint16_t *mark2)
 アロケートされたメモリに付加された情報を取得します。 [詳解]
 
void * nmalloc_getobjptr (void *raw_ptr)
 nmalloc_heapwalk_callbackに渡されたポインタをオブジェクトへのポインタに変換します。 [詳解]
 

詳解

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

マクロ定義詳解

#define NMALLOC_HEAPOPTION_CACHE_DISABLE   (0x00000004)

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

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

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

#define NMALLOC_HEAPOPTION_CHECK_0   (0x00000000)

デフォルト設定で最も効率よく動作します。

説明
NMALLOC_HEAPOPTION_ENABLE_ENVが指定されている場合は、環境変数NLIB_NMALLOC_MODEを0に設定することで、ソースコード上の設定をこの設定に上書きすることが可能です。

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

#define NMALLOC_HEAPOPTION_CHECK_1   (0x00000008)

16bitのメタデータを2つ設定可能にします。メモリの先頭部分のデータ破壊を検出します。

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

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

型定義詳解

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.h67 行目に定義があります。

列挙型詳解

nmalloc_dumpex()関数に渡す引数の型です。

列挙値
NMALLOC_DUMP_BASIC 

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

NMALLOC_DUMP_SPANS 

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

NMALLOC_DUMP_POINTERS 

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

NMALLOC_DUMP_ALL 

情報を全て表示します。

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

関数詳解

ncalloc ( size_t  nmemb,
size_t  size 
)

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

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

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

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

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

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

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

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

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

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

実行中のスレッドにキャッシュされている割り当て可能なメモリを中央ヒープに返します。

説明
nmallocは各スレッドに割り当て可能なメモリをキャッシュすることで高速化を行なっていますが、この関数を呼び出すことでキャッシュされている割り当て可能メモリを中央ヒープ(CentralHeap)に明示的に返却します。
各種例:
heap/nmalloc_withstl/nmalloc_withstl.cpp, heap/replace_malloc/replace_malloc.cpp.
nmalloc_dump ( void  )

ヒープの基本的な状況をダンプします。

説明
nmalloc_dumpex(NMALLOC_DUMP_BASIC)と等価です。
void nmalloc_dumpex ( NMallocDumpMode  mode)

ヒープの状況をダンプします。

引数
[in]mode表示オプションです。
説明
TODO(nishida_kenji): タグの仕様が固まったら詳しく説明を書くこと。
各種例:
heap/nmalloc_simple/nmalloc_simple.cpp, heap/nmalloc_withstl/nmalloc_withstl.cpp, heap/replace_malloc/replace_malloc.cpp.
void nmalloc_dumpex2 ( NMallocDumpMode  mode,
nlib_fd  fd 
)

ヒープの状況をダンプします。

引数
[in]mode表示オプションです。
[in]fd表示対象のファイルディスクリプタです。
説明
TODO(nishida_kenji): タグの仕様が固まったら詳しく説明を書くこと。
nmalloc_finalize_tls ( void  )

実行中のスレッド固有のメモリを全て中央ヒープに返却します。スレッドを終了させるときに呼び出す必要があります。

説明
nmalloc_clear_tls()に加えて、キャッシュ管理用のデータ領域も中央ヒープ(CentralHeap)に返却します。
各種例:
heap/nmalloc_simple/nmalloc_simple.cpp.
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_getmark ( const void *  ptr,
uint16_t *  mark1,
uint16_t *  mark2 
)

アロケートされたメモリに付加された情報を取得します。

引数
[in]ptrアロケートしたオブジェクトのポインタ
[out]mark116bitの付加情報その1が格納されるポインタ。NULL指定可
[out]mark216bitの付加情報その2が格納されるポインタ。NULL指定可
戻り値
0ならば成功
説明
内部でCachedHeap::GetMark()を実行します。 詳しくは、CachedHeap::GetMark()を御覧ください。
nmalloc_getobjptr ( void *  raw_ptr)

nmalloc_heapwalk_callbackに渡されたポインタをオブジェクトへのポインタに変換します。

引数
[in]raw_ptrnmalloc_heapwalk_callback に渡されたポインタ
戻り値
オブジェクトのポインタ
説明
内部でCachedHeap::GetObjPtr()を実行します。 詳しくは、CachedHeap::GetObjPtr()を御覧ください。
nmalloc_heaphash ( HeapHash hash)

ユーザーによるメモリ確保状況を調べてサマリを作成します。

引数
[in]hashサマリが格納される構造体
説明
中央ヒープ(nn::nlib::heap::CentralHeap)の割り当て状況を調査し、サマリを計算します。 メモリリークの調査等に利用することが可能です。
ただし、各スレッドにキャッシュされている割り当て可能なメモリは確保されているものとしてサマリが計算されます。 従って、メモリリークしていないのにサマリが異なる、といった状況がありえます。
これを避けるにはオプションにNMALLOC_HEAPOPTION_CACHE_DISABLEを指定してヒープを初期化するか、事前にnmalloc_clear_tls()を全てのスレッドで呼び出しておきます。
各種例:
heap/nmalloc_leakcheck/nmalloc_leakcheck.cpp.
nmalloc_isclean ( void  )

ヒープの状態が初期化直後と同じかどうか確認します。

戻り値
ヒープの状態が初期化直後と同じならばtrue
説明
全てのメモリの解放後(nmalloc_finalize_tls()によるスレッド毎のキャッシュの解放も含む)に呼び出すことで、ヒープの状態を厳密にチェックすることができます。 ヒープの状態がメタデータも含めて初期化直後の状態と同じかチェックします。 従ってメモリリークしていなくても失敗することがあります。
各種例:
heap/nmalloc_simple/nmalloc_simple.cpp.
nmalloc_setmark1 ( void *  p,
uint16_t  mark1 
)

アロケートされたメモリに情報を付加します。

引数
[in]pアロケートしたオブジェクトのポインタ
[in]mark116bitの付加情報その1
戻り値
0ならば成功
説明
内部でCachedHeap::SetMark1()を実行します。 詳しくは、 CachedHeap::SetMark1() を御覧ください。
nmalloc_setmark2 ( void *  p,
uint16_t  mark2 
)

アロケートされたメモリに情報を付加します。

引数
[in]pアロケートしたオブジェクトのポインタ
[in]mark216bitの付加情報その2
戻り値
0ならば成功
説明
内部でCachedHeap::SetMark2()を実行します。 詳しくは、CachedHeap::SetMark2()を御覧ください。
nmalloc_size ( const void *  ptr)

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

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

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

引数
[in]funcコールバック関数
[in]user_ptrユーザー用ポインタ
戻り値
0ならば成功
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.

変数詳解

NMallocSettings::heap_option

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

説明
効果
NMALLOC_HEAPOPTION_ENABLE_ENV 環境変数による設定の上書きを有効にします。
NMALLOC_HEAPOPTION_CACHE_DISABLE CachedHeapによるキャッシングを無効にします。
NMALLOC_HEAPOPTION_CHECK_0 デフォルト設定で最も効率よく動作します。
NMALLOC_HEAPOPTION_CHECK_1 16bitのメタデータを2つ設定可能にします。メモリの先頭部分のデータ破壊を検出します。
各種例:
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 行目に定義があります。

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 行目に定義があります。