EN JA
JEMALLOC(3)
JEMALLOC(3) User Manual JEMALLOC(3)

名称

jemalloc -汎用メモリ割り付け関数

ライブラリ

このマニュアルは、jemalloc 3.4.0-0-g0ed518e5dab789ad2171bb38977a8927e2a26775 を説明しています。より多くの情報は、 jemalloc ウェブサイト[1] で見つけることができます。

次の設定オプションが、libc 組み込み jemalloc で有効にされます: --enable-dss, --enable-experimental, --enable-fill, --enable-lazy-lock, --enable-munmap, --enable-stats, --enable-tcache, --enable-tls, --enable-utrace, and --enable-xmalloc. さらに、 --enable-debug は、( MALLOC_PRODUCTION make 変数によって制御される) FreeBSD の開発バージョンで有効にされます。

書式


#include <stdlib.h>
#include <malloc_np.h>

標準 API

void *malloc(size_t size);

void *calloc(size_t number, size_t size);

int posix_memalign(void **ptr, size_t alignment, size_t size);

void *aligned_alloc(size_t alignment, size_t size);

void *realloc(void *ptr, size_t size);

void free(void *ptr);

非標準 API

size_t malloc_usable_size(const void *ptr);

void malloc_stats_print(void (*write_cb) (void *, const char *), void *cbopaque, const char *opts);

int mallctl(const char *name, void *oldp, size_t *oldlenp, void *newp, size_t newlen);

int mallctlnametomib(const char *name, size_t *mibp, size_t *miblenp);

int mallctlbymib(const size_t *mib, size_t miblen, void *oldp, size_t *oldlenp, void *newp, size_t newlen);

void (*malloc_message)(void *cbopaque, const char *s);

const char * malloc_conf;

実験的 API

int allocm(void **ptr, size_t *rsize, size_t size, int flags);

int rallocm(void **ptr, size_t *rsize, size_t size, size_t extra, int flags);

int sallocm(const void *ptr, size_t *rsize, int flags);

int dallocm(void *ptr, int flags);

int nallocm(size_t *rsize, size_t size, int flags);

解説

標準 API

malloc 関数は、 size バイトの初期化されていないメモリを割り付けます。割り付けられた空間は、あらゆるタイプのオブジェクトの記憶域のために (可能なポインタ強制の後に) 適切に整列されます

calloc 関数は、各 size バイトの長さの number 個のオブジェクトのための空間を割り付けます。割り付けてられたメモリが明示的に 0 バイトに初期化されることを除いて、 number * size の引数で malloc を呼び出すことと結果は、同一です。

posix_memalign 関数は、割り付けのベースアドレスが alignment の偶数倍であるように size バイトのメモリを割り付け、 ptr によって指された値に割り付けを返します。要求された alignment は、少なくとも sizeof( void *) と同じ大きさの 2 のべき乗でなければなりません。

aligned_alloc 関数は、割り付けのベースアドレスが alignment の偶数倍であるように size バイトのメモリを割り付けます。要求された alignment は、2 のべき乗でなければなりません。 sizealignment の整数倍でないなら、振る舞いは、未定義です。

realloc 関数は、 ptr によって参照される以前に割り付けられたメモリのサイズを size バイトに変更します。メモリの内容は、新しいサイズのより小さい部分と古いサイズの部分は変更されないままです。新しいサイズがより大きいなら、メモリの新しく割り付けられた部分の内容は、未定義です。成功すれば、 ptr によって参考されるメモリは、解放され、新しく割り付けられたメモリへのポインタが返されます。 realloc は、 ptr とは異なっている返り値の結果となるように、メモリ割り付けを移動するかもしれないことに注意してください。 ptrNULL であるなら、 realloc 関数は、指定されたサイズのための malloc と同じように振る舞います。

free 関数によって、 ptr によって参照される割り付けられたメモリは、将来の割り付けのために利用可能とされます。 ptrNULL であるなら、何もアクションは、取られません。

非標準 API

malloc_usable_size 関数は、 ptr によって指される割り付けの使用可能なサイズを返します。返り値は、割り付けの間に要求されたサイズより大きいかもしれません。 malloc_usable_size 関数は、整っている realloc のためのメカニズムではありません。とちらかといえば、もっぱら内歓 (introspection) 目的のためのツールとして提供されています。そのような振る舞いは、完全に実装依存であるので、要求された割り付けサイズと malloc_usable_size によって報告されたサイズの間のあらゆる不一致に依存するべきではありません。

malloc_stats_print 関数は、 write_cbNULL であるなら、 write_cb コールバック関数ポインタ、 write_cb または malloc_messageに渡された cbopaque データによって人間に読み込み可能な要約された統計値を書き込みます。この関数は、繰り返し呼び出すことができます。実行の間に決して変化しなし一般的な情報は、 opts 文字列内の文字として "g"を指定することによって省略することができます。 malloc_message は、 mallctl* 関数を内部的に使用するので、複数のスレッドが、これらの関数を同時に使用するなら、一貫性のない統計値を報告するかもしれないことに注意してください。 --enable-stats が設定の間に指定されるなら、それぞれマージされたアリーナ (arena) とアリーナごとの統計を省略するために、“m”と“a”を指定することができます。それぞれ、bins のためのサイズクラスの統計値ごとと大きなオブジェクトを省略するために“b”と“l”を指定することができます。認識されない文字は、静かに無視されます。特別のロックがスレッドキャッシュ操作を追跡するカウンタをマージするように要求されるので、スレッドのキャッシングは、完全に最新のことからいくつかの統計値を防ぐかもしれないことに注意してください。

mallctl 関数は、設定する修正可能なパラメータと引き金を引くアクションと同様に、メモリアロケータを内歓するための一般的なインタフェースを提供します。ピリオドで区切られた name 引数は、ツリー構造した名前空間の位置を指定します。ツリーの内容に関する文書については、「MALLCTL 名前空間」セクションを参照してください。値を読み込むためには、値を含んでいる適切な空間への oldp を介したポインタと、 oldlenp を介した、その長さへのポインタを渡します。そうでなければ、 NULLNULL を渡します。同様に、値を書き込むためには、 newp を介した値へのポインタと newlen を介したその長さ渡します。そうでなければ、 NULL0 を渡します。

mallctlnametomib 関数は、 mallctlbymib に繰り返し渡すことができる“管理情報ベース” (MIB) に名前を変換することによって、名前空間の同じ部分を繰り返し問い合わせるアプリケーションのために繰り返された名前の検索を回避する方法を提供します。 mallctlnametomib から成功して返るとき、 mibp は、 *miblenp 整数の配列を含んでいます、ここで *miblenp は、 name のコンポーネントの数と *miblenp の入力値のより小さいものです。したがって、完全な MIB を構築するための基本として使用することができる部分的な MIB の結果である、ピリオドで区切られた名前のコンポーネントの数より小さい *miblenp を渡すことは可能です。整数である名前コンポーネント (例えば、"arenas.bin.2.size"の 2) について、対応する MIB のコンポーネントは、常にその整数になります。したがって、次のようなコードを構築することは正当です:

 

unsigned nbins, i;


int mib[4];
size_t len, miblen;


len = sizeof(nbins);
mallctl("arenas.nbins", &nbins, &len, NULL, 0);


miblen = 4;
mallnametomib("arenas.bin.0.size", mib, &miblen);
for (i = 0; i < nbins; i++) {
size_t bin_size;


mib[2] = i;
len = sizeof(bin_size);
mallctlbymib(mib, miblen, &bin_size, &len, NULL, 0);
/* bin_size で何かを行う... */
}

実験的 API

実験的な API は、後方互換性などお構いなしに変更または削除の対象です。 --disable-experimental が設定の間に指定されなら、実験的な API は、省略されます。

allocm, rallocm, sallocm, dallocmnallocm 関数は、すべて、オプションを指定するために使用することができる flags 引数があります。関数は、文脈的に適切なオプションのみをチェックします。次の 1 つ以上を指定するためには、ビット単位の OR (|) 演算を使用します:

ALLOCM_LG_ALIGN(la)

(1 << la) の倍数であるアドレスで開始するためにメモリ割り付けを整列します。このマクロは、 la が有効な範囲内であることを確認にしません。

ALLOCM_ALIGN(a)

a の倍数であるアドレスで開始するためにメモリ割り付けを整列します、ここで、 a は、2 のべき乗です。このマクロは、 a が、2 のべき乗であることを確認しません。

ALLOCM_ZERO

0 バイトを含むように新しく割り付けられたメモリを初期化します。増加している再割り付けの場合に、再割り付けの前の実際のサイズは、変更されないバイトと 0 バイトを含むように初期化されるものの間の境界を定義します。このオプションがないなら、新しく割り付けられたメモリは、初期化されていません。

ALLOCM_NO_MOVE

再割り付けについては、オブジェクトを移動させずに失敗します。この制約は、増加と縮小の両方に適用することができます。

ALLOCM_ARENA(a)

インデックス a によって指定されたアリーナを使用します。このマクロは、 a が有効な範囲中のアリーナを指定することを有効にしません。

allocm 関数は、少なくとも size バイトのメモリを割り付け、 *ptr を割り付けのベースアドレスに設定し、 rsizeNULLでないなら、 *rsize を割り付けの実際のサイズに設定します。 size0であるなら、振る舞いは、未定義です。

rallocm 関数は、少なくとも size バイトとなるように *ptr で割り付けをサイズ変更し、それが移動したなら、 *ptr を割り付けのベースアドレスに設定し、 rsizeNULL でないなら、 *rsize を割り付けの実際のサイズに設定します。 extra が 0 でないなら、少なくとも ( size + extra) バイトとなるように割り付けサイズを変更する試みが行われますが、特別な (複数の) バイトを割り付けるための能力は、失敗でそれ自体の結果によってではなく、ありません。 size0であるか、または ( size + extra > SIZE_T_MAX) であるなら、振る舞いは、未定義です。

sallocm 関数は、 *rsize を割り付けの実際のサイズに設定します。

dallocm 関数によって ptr によって参照されたメモリは、将来の割り付けのために利用可能にします。

nallocm 関数は、メモリを割り付けませんが、 allocm 関数のように同じサイズの計算を行ない、 rsizeNULL でないなら、 *rsize を同等な allocm 関数呼出しからの結果である割り付けの実際のサイズに設定します。 size0 であるなら、振る舞いは、未定義です。

調整

いったん、最初の呼び出しがメモリ割り付けルーチンのうちの 1 つで行われるとき、アロケータ (割り付けルーチン) は、コンパイル時、または実行時に指定することができる、様々なオプションの一つに基づいてその内部を初期化します、

グローバル変数 malloc_conf によって指される文字列、 /etc/malloc.conf と名前が付けられたシンボリックリンクによって参照されるファイルの“name”と環境変数 MALLOC_CONF の値は、オプションとして左から右の順序で解釈されます。 main に入る前に malloc_conf は、読み込まれるので、 malloc_conf の宣言は、jemalloc によって読み込まれる最後の値を含んでいる初期化ルーチン (initializer) を指定するべきであることに注意してください。 malloc_conf は、コンパイル時間の設定ですが、一方プログラヌの呼び出しの前のいつでも /etc/malloc.conf と MALLOC_CONF を安全に設定することができます。

オプションの文字列は、コンマで区切られた option:value (オプション:値) のペアのリストです。各 "opt.*" mallctl に対応する 1 つのキーがあります (オプションの文書については、「MALLCTL 名前空間」セクションを参照)。例えば、 abort:true,narenas:1 は、 "opt.abort"と "opt.narenas"オプションを設定します。いくつかのオプションには、ブール値の値 (真/偽) があり、他のものには、整数値 (接頭辞に依存して、8、10、または 16) があり、さらに他のものには、生の文字列の値があります。

実装に関する注

伝統的に、アロケータは、最大の使用可能なメモリに関して、競合条件、増強された断片化と人為的な制限を含んで、いくつかの理由で準最適である、メモリを獲得するために sbrk(2) を使用しました。 --enable-dss 設定の間に指定されなら、このアロケータは、その優先の順位で、 mmap(2) と sbrk(2) の両方を使用します。そうでなければ、 mmap(2) だけが使用されます。

このアロケータは、マルチプロセッサのシステムでスレッド化されたプログラムのためのロックの競合を縮小するために複数のアリーナを使用します。これは、スレッド化の拡張可能性に関してうまくいきますが、いくらかのコストを負います。固定のアリーナごとに小さなオーバヘッドがあり、さらに、アリーナは、全体的なメモリの断片化の小さな固定された増加を意味する、互いに完全に独立したメモリを管理します。これらのオーバヘッドは、通常使用されるアリーナの数を考えると、一般的に問題ではありません。デフォルトより実質的により多くのアリーナを使用することは、主として縮小されたキャッシュの性能のために、性能を向上しそうにないことに注意してください。しかしながら、アプリケーションがあまり割り付け関数を使用しないなら、アリーナの数を減らすことは意味があります。

複数のアリーナに加えて、 --disable-tcache が設定の間に指定されなければ、このアロケータは、ほとんどの割り付け要求のための同期を完全に回避することを可能にするために、スモールとラージ (small と large) オブジェクトのためのスレッド特有のキャッシュをサポートしています。そのようなキャッシングによって、通常の場合に非常に速い割り付けができますが、各スレッドのキャッシュでオブジェクトの境界のある数を割り付けたままであるかもしれないので、メモリの使用量と断片化を増加させます。

メモリは、概念的に等しいサイズのチャンクに分割されます、ここで、チャンクサイズは、ページサイズより大きい 2 のべき乗です。チャンクは、常にチャンクサイズの倍数に整列されます。この整列は、ユーザオブジェクトのためのメタデータをとても速く見つけることを可能にします。

ユーザオブジェクトは、サイズに従って、3 つのカテゴリに分割されます: スモール (small)、ラージ (large) とヒュージ (huge) です。スモールオブジェクトは、1 ページより小さいものです。ラージオブジェクトは、チャンクサイズより小さいものです。ヒュージオブジェクトは、チャンクサイズの倍数です。スモールとラージオブジェクトは、アリーナによって管理されます。ヒュージオブジェクトは、すべてのスレッドによって共有される単一のデータ構造で別々に管理されます。ヒュージオブジェクトは、アプリケーションによってごくまれに使用されるので、この単一のデータ構造は、拡張可能性の問題がありません。

アリーナによって管理される各チャンクは、隣接するページ (未使用、裏打ちされた 1 組のスモールオブジェクトまたは裏打ちされた 1 つのラージオブジェクト) の実行としてその内容を追跡します。チャンクの整列とチャンクのページマップの組み合わせによって、一定の時間で小さなものと大きなものの割り付けに関するすべてのメタデータを決定することを可能にします。

スモールオブジェクトは、ページの等級 (run) によってグループで管理されます。各等級は、境界 (frontier) を管理し、どの領域が使用中であるかを追跡するリストを解放します。 (アーキテクチャに依存して、8 または 16) の半分以下の量の割り付け要求は、少なくとも sizeof( double) である最も近い 2 のべき乗に丸められます。他のすべてのスモールオブジェクトのサイズのクラスは、内部の断片化が最も小さなサイズのクラス以外のために約 25% に制限されたような空間をとる量の倍数です、アリーナに管理されたチャンク ("opt.lg_chunk"オプションを参照) に適合するために十分に小さいけれども、最大のスモールサイズのクラスより大きい割り付け要求は、最も近い階級のサイズまで丸められます。アリーナに管理されたチャンクに適合するには大きすぎる割り付け要求は、チャンクサイズの最も近い倍数に丸められます。

割り付けは、マルチスレッド化されたアプリケーションのために問題となるかもしれませんが、とともにしっかりパックされます。割り付けがキャッシュライン (cacheline) の共有に悩まされないことを保証する必要があるなら、利用者の割り付け要求をキャッシュラインサイズの最も近い倍数まで丸めるか、または割り付けるとき、キャッシュラインの整列を指定します。

4 MiB のチャンク、4 KiB ページと 64 ビットのシステムでの 16 バイトの量を仮定して、各カテゴリのサイズのクラスは、表 1 に表示される通りです。

 
 

表 1. サイズクラス

カテゴリ 間隔 サイズ
スモール lg [8]
16 [16, 32, 48, ..., 128]
32 [160, 192, 224, 256]
64 [320, 384, 448, 512]
128 [640, 768, 896, 1024]
256 [1280, 1536, 1792, 2048]
512 [2560, 3072, 3584]
ラージ 4 KiB [4 KiB, 8 KiB, 12 KiB, ..., 4072 KiB]
ヒュージ 4 MiB [4 MiB, 8 MiB, 12 MiB, ...]
 

MALLCTL 名前空間

次の名前は、 mallctl* 関数によってアクセス可能な名前空間に定義されています。値のタイプは、括弧の中に指定され、それらの読み込み可能/書き込み可能な状態は、 rw, r-, -w または--としてエンコードされ、要求された構築設定フラグは、もしあるなら、従います。 <i>または <j>としてエンコードされた名前の要素は、整数の構成要素を示します、ここで整数は、0 から内観によって決定されなければならないある上位の値まで変化します。 "stats.arenas.<i>.*"の場合に、 "arenas.narenas"と等しい <i>は、すべてのアリーナから統計値の要約にアクセスするために使用することができます。キャッシュされた動的な統計値のリフレッシュを制御する、 "epoch" mallctl の特別の注記を取ります。

"version" ( const char *) r-

jemalloc バージョンの文字列を返します。

"epoch" ( uint64_t) rw

値が渡されるなら、 mallctl* 関数は、値を報告し、epoch を増加するデータをリフレッシュします。現在の epoch を返します。これは、別のスレッドがリフレッシュを引き起こしたかどうかを検出するために役に立ちます。

"config.debug" ( bool) r-

--enable-debug は、構築設定の間に指定されました。

"config.dss" ( bool) r-

--enable-dss は、構築設定の間に指定されました。

"config.fill" ( bool) r-

--enable-fill は、構築設定の間に指定されました。

"config.lazy_lock" ( bool) r-

--enable-lazy-lock は、構築設定の間に指定されました。

"config.mremap" ( bool) r-

--enable-mremap は、構築設定の間に指定されました。

"config.munmap" ( bool) r-

--enable-munmap は、構築設定の間に指定されました。

"config.prof" ( bool) r-

--enable-prof は、構築設定の間に指定されました。

"config.prof_libgcc" ( bool) r-

--disable-prof-libgcc は、構築設定の間に指定されませんでした。

"config.prof_libunwind" ( bool) r-

--enable-prof-libunwind は、構築設定の間に指定されました。

"config.stats" ( bool) r-

--enable-stats は、構築設定の間に指定されました。

"config.tcache" ( bool) r-

--disable-tcache は、構築設定の間に指定されませんでした。

"config.tls" ( bool) r-

--disable-tls は、構築設定の間に指定されませんでした。

"config.utrace" ( bool) r-

--enable-utrace は、構築設定の間に指定されました。

"config.valgrind" ( bool) r-

--enable-valgrind は、構築設定の間に指定されました。

"config.xmalloc" ( bool) r-

--enable-xmalloc は、構築設定の間に指定されました。

"opt.abort" ( bool) r-

有効にされた/無効にされた警告中のアボート。真であるなら、ほとんどの警告は、致命的です。プロセスは、これらの場合に abort(3) を呼び出します。このオプションは、デフォルトで無効になります、 --enable-debug が設定の間に指定されない場合は、デフォルトで有効になります。

"opt.lg_chunk" ( size_t) r-

仮想メモリのチャンクサイズ。(2 を底とする対数 (log))。サポートされているサイズ範囲の外側のチャンクサイズが指定されるなら、サイズは、サポートされているサイズの最小/最大の範囲に静かに刈り込まれます。デフォルトのチャンクサイズは、4 MiB (2^22) です。

"opt.dss" ( const char *) r-

mmap(2) 割り付けに関連づけられる dss ( sbrk(2)) 割り付けの優先順位。次の設定がサポートされます: “disabled”, “primary”と“secondary” (デフォルト)。

"opt.narenas" ( size_t) r-

スレッドとアリーナの自動多重化のために使用するアリーナの最大数。デフォルトは、CPU の数の 4 倍、または単一の CPU があるなら、1 です。

"opt.lg_dirty_mult" ( ssize_t) r-

ページをダーティにするアクティブのアリーナごとの最小の比率 (2 を底とする対数 (log))。いくつかのダーティな未使用のページは、 madvise(2) または同様のシステムコールによって、それらのページのうちのいくつかに関してカーネルに通知する前に、比率 (または、ダーティなページの 1 つのチャンクの価値、どちらか大きい方) によって設定される制限内で、蓄積することが許可されます。これは、物理メモリが少なくなり、ページが未使用のままであるなら、ダーティなページを再利用するための十分な情報をカーネルに提供します。デフォルト最小の比率は、8:1 (2^3:1) です。-1 のオプションの値は、ダーティなページの消去を無効にします。

"opt.stats_print" ( bool) r-

終了時に印刷する統計値を有効に/無効にします。有効であるなら、 malloc_stats_print 関数は、 atexit(3) 関数によってプログラムの終了時に呼び出されます。 --enable-stats が設定の間に指定されるなら、これには、1 つ以上のスレッドがメモリ割り付け関数で実行している間に、終了するマルチスレッドのプロセスのためのデッドロックを引き起こす可能性があります。したがって、このオプションは、注意して使用されるべきです。それは、主として、アプリケーション開発の間の性能の調整の援助することを目的としています。このオプションは、デフォルトで無効にされます。

"opt.junk" ( bool) r- [ --enable-fill]

有効にされる/無効にされるジャンクの詰め物。有効にされるなら、初期化されていない割り付けられたメモリの各バイトは、 0xa5 で初期化されます。すべての割り付け解放されたメモリは、0x5a で初期化されます。これは、デバッグを対象としていて、性能に悪影響を与えます。このオプションは、 --enable-debug が設定の間に指定されなければ、デフォルトで無効にされ、設定されない場合に、 Valgrind[2] の内部で実行されなければ、デフォルトで有効になります。

"opt.quarantine" ( size_t) r- [ --enable-fill]

バイト単位のスレッドごとの隔離された (quarantine) サイズ。 0 でないなら、各スレッドは、メモリの指定された数のバイトまで格納する FIFO オブジェクトの隔離を維持します。隔離されたメモリは、 "opt.junk"オプションが有効にされるなら、直ちにジャンクの詰め物されますが、隔離から解放されるまで、解放されません。この機能は、隔離されたオブジェクトにアクセスする試みを検出することができる、 Valgrind[2] と組み合わせて特に使用されます。これは、デバッグを対象としていて、性能に悪影響を与えます。デフォルトの隔離サイズは、Valgrind の内部で実行されなければ、0 で、その場合に、デフォルトは、16 MiB です。

"opt.redzone" ( bool) r- [ --enable-fill]

有効にされる/無効にされるレッドゾーン。有効にされるなら、小さな割り付けは、それらの前と後にレッドゾーンがあります。さらに、 "opt.junk"オプションが有効にされるなら、レッドゾーンは、割り付け解除の間に、破壊があるかチェックされます。しかしながら、この機能の意図する主な目的は、バッファオーバフロー/アンダフローの検出を効率的に行うためにレッドゾーンを必要とする、 Valgrind[2] と組み合わせて使用されることです。これは、デバッグを対象としていて、性能に悪影響を与えます。このオプションは、Valgrind の内部で実行されなければ、デフォルトで無効にされます。

"opt.zero" ( bool) r- [ --enable-fill]

有効にされる/無効にされる 0 の詰め物。有効にされるなら、初期化されていない割り付けられたメモリの各バイトは、0 で初期化されます。この初期化は、各バイトに対して一度だけ起こるので、 realloc rallocm 呼び出しは、以前に割り付けられたメモリを 0 にしないことに注意してください。これはデバッグを意図し、実行に否定的に影響を与えるでしょう。このオプションは、デフォルトで無効にされます。

"opt.utrace" ( bool) r- [ --enable-utrace]

有効にされる/無効にされる utrace(2) に基づいた、割り付けの追跡。このオプションは、デフォルトで無効にされます。

"opt.valgrind" ( bool) r- [ --enable-valgrind]

有効にされる/無効にされる Valgrind[2] サポート。 jemalloc は、Valgrind の内部で実行されているかどうか、自動検出するので、このオプションは、vestigal です。訳注: vestigal の意味不明。このオプションは、Valgrind の内部で実行されなければ、デフォルトで無効にされます。

"opt.xmalloc" ( bool) r- [ --enable-xmalloc]

有効にされる/無効にされるメモリ不足でのアボート (Abort-on-out-of-memory)。有効にされるなら、任意の割り付け関数のために失敗を返すのではなく、 STDERR_FILENO の診断メッセージを表示して、プログラムが ( abort(3) を使用して) コアを落とします。アプリケーションが、この振る舞いに依存するように設計されているなら、ソースコードに次を含めることによって、コンパイル時にオプションを設定します:
 

malloc_conf = "xmalloc:true";
 
このオプションは、デフォルトで無効にされます。

"opt.tcache" ( bool) r- [ --enable-tcache]

有効にされる/無効にされるスレッド特有のキャッシング。複数のスレッドがあるとき、各スレッドは、特定のサイズまでのオブジェクトのためにスレッド特有のキャッシュを使用します。スレッド特有のキャッシングによって、増加したメモリの使用を犠牲にして、あらゆるスレッドの同期を行なわずに多くの割り付けを、満足させることができます。関連する調整の情報については、 "opt.lg_tcache_max"オプションを参照してください。このオプションは、 Valgrind[2] の内部で実行されなければ、デフォルトで有効にされます。

"opt.lg_tcache_max" ( size_t) r- [ --enable-tcache]

スレッド特有のキャッシュでキャッシュする最大サイズのクラス (2 を底とする対数 (log))。最小では、すべての小さなサイズのクラスは、キャッシュされ、最大では、すべての大きなサイズのクラスは、キャッシュされます。デフォルトの最大は、32 KiB (2^15) です。

"opt.prof" ( bool) r- [ --enable-prof]

有効にされる/無効にされるメモリのプロファイリング。有効にされるなら、メモリ割り付けの動作をプロファイルします。オンザフライ (on-the-fly) の活性化/非活性化については、 "opt.prof_active"オプションを参照してください。確率的なサンプリングの制御については、 "opt.lg_prof_sample"オプションを参照してください。累積されたサンプル報告の制御については、 "opt.prof_accum"オプションを参照してください。間隔 (interval) の引き金となるプロファイルのダンプの情報については、 "opt.lg_prof_interval"オプションを、高水位 (high-water) の引き金となるプロファイルのダンプの情報については、 "opt.prof_gdump"オプションを、最終のプロファイルのダンプついては、 "opt.prof_final"オプションを参照してください。プロファイルの出力は、 gperftools パッケージ[3] を起源とする、含まれる pprof Perl スクリプトと互換性があります。

"opt.prof_prefix" ( const char *) r- [ --enable-prof]

プロファイルのダンプのためのファイル名の接頭辞。接頭辞が空の文字列に設定されるなら、自動的にダンプは、起こりません。これは、(また、有効にされるなら、リークの (leak) 報告を無効にする) 自動的な最終のヒープダンプを無効にするために主として役に立ちます。デフォルトの接頭辞は、 jeprof です。

"opt.prof_active" ( bool) r- [ --enable-prof]

活性化される/非活性化されるプロファイリング。これは、不活発ですが、有効にされたプロファイリング ("opt.prof"オプション参照) でアプリケーションを開始することを可能にする二次的制御メカニズムです、次に、 "prof.active" mallctl でプログラム実行の間にいつでもプロファイリングを切り替えます。このオプションは、デフォルトで有効にされます。

"opt.lg_prof_sample" ( ssize_t) r- [ --enable-prof]

割り付け動作のバイト単位で測定された割り付けサンプルの間の平均の間隔 (2 を底とする対数 (log))。サンプリングの間隔を増加させることは、プロファイルの忠実性を減少させますが、また、計算のオーバヘッドを減少させます。デフォルトのサンプル間隔は、512 KiB (2^19 B) です。

"opt.prof_accum" ( bool) r- [ --enable-prof]

有効にされる/無効にされるプロファイルダンプの累積されたオブジェクト/バイトのカウントの報告。このオプションが有効にされるなら、すべてのユニークなバックトレース (backtrace) は、実行の継続期間に格納されなければなりません。アプリケーションによって、これは、大きなメモリのオーバヘッドを与えるかもしれません、そして、累積されるカウントは、必ずしも興味深いとは限りません。このオプションは、デフォルトで無効にされます。

"opt.lg_prof_interval" ( ssize_t) r- [ --enable-prof]

割り付け動作のバイト単位で測定されたメモリプロファイルの間の平均の間隔 (2 を底とする対数 (log))。ダンプ間の実際の間隔は、分散化された割り付けカウンタは、同期のボトルネックを回避するために使用されるので、散発的であるかもしれません。プロファイルは、パターン <prefix>.<pid>.<seq>.i<iseq>.heap に従って名前を付けられたファイルにダンプされます、ここで、 <prefix>は、 "opt.prof_prefix"オプションによって制御されます。デフォルトで、間隔で引き金となるプロファイルのダンプは、 (-1 としてエンコードされ) 無効にされます。

"opt.prof_gdump" ( bool) r- [ --enable-prof]

以前の最大を超過する合計の仮想メモリごとに、メモリプロファイルのダンプの引き金となります。プロファイルは、パターン <prefix>.<pid>.<seq>.u<useq>.heap に従って名前を付けられたファイルにダンプされます、ここで、 <prefix>は、 "opt.prof_prefix"オプションによって制御されます。このオプションは、デフォルトで無効にされます。

"opt.prof_final" ( bool) r- [ --enable-prof]

パターン <prefix>.<pid>.<seq>.f.heap に従って名前を付けられたファイルに最後のメモリ使用量をダンプする atexit(3) 関数を使用します、ここで、 <prefix>は、 "opt.prof_prefix"オプションによって制御されます。このオプションは、デフォルトで有効にされます。

"opt.prof_leak" ( bool) r- [ --enable-prof]

有効にされる/無効にされるリーク (leak) の報告。有効にされるなら、割り付けサンプリングによって検出されたメモリリークを報告するために atexit(3) 関数を使用します。ヒープのプロファイル出力の解析に関する情報については、 "opt.prof"オプションを参照してください。このオプションは、デフォルトで無効にされます。

"thread.arena" ( unsigned) rw

呼び出しているスレッドに関連するアリーナを取得するか、設定します。指定されたアリーナがあらかじめ初期化されていないなら ("arenas.initialized" mallctl 参照)、このインタフェースを呼び出す副作用として自動的に初期化されます。

"thread.allocated" ( uint64_t) r- [ --enable-stats]

呼び出しているスレッドによってかつて割り付けられたバイトの合計数を取得します。このカウンタには、ラップアラウンド (wrap around) する可能性があります。そのような場合にカウンタを適切に解釈することはアプリケーション次第です。

"thread.allocatedp" ( uint64_t *) r- [ --enable-stats]

"thread.allocated" mallctl によって返された値へのポインタを取得します。これは、繰り返された mallctl* 呼び出しのオーバヘッドを回避するのに役に立ちます。

"thread.deallocated" ( uint64_t) r- [ --enable-stats]

呼び出しているスレッドよってかつて割り付け解放されたバイトの合計数を取得します。このカウンタには、ラップアラウンド (wrap around) する可能性があります。そのような場合に、カウンタを適切に解釈することはアプリケーション次第です。

"thread.deallocatedp" ( uint64_t *) r- [ --enable-stats]

"thread.deallocated" mallctl によって返された値へのポインタを取得します。これは、繰り返された mallctl* 呼び出しのオーバヘッドを回避するのに役に立ちます。

"thread.tcache.enabled" ( bool) rw [ --enable-tcache]

呼び出しているスレッドの tcache を有効に/無効にします。 tcache は、無効になる副作用として暗黙のうちにフラッシュされます ("thread.tcache.flush"参照)。

"thread.tcache.flush" ( void) -- [ --enable-tcache]

呼び出しているスレッドの tcache をフラッシュします。このインタフェースは、呼び出しているスレッドのスレッド特有のキャッシュに関連したすべてのキャッシュに入れられたオブジェクトと内部データ構造を解放します。通常、自動的な周期の増加するガーベジコレクションが生じる、スレッドが終了するとき、スレッドのキャッシュが、自動的に廃棄されるので、このインタフェースを呼び出す必要はありません。しかしながら、ガーベジコレクションは、割り付け動作が引き金となるので、そのキャッシュを無期限に保持するために割り付け/割り付け解放を停止するスレッドに可能です、その場合に、開発者は、手動のフラッシュが役に立つのが分かります。

"arena.<i>.purge" ( unsigned) --

アリーナ <i>の、または <i>が "arenas.narenas"と等しいなら、すべてのアリーナの未使用の汚い (dirty) ページを削除します。

"arena.<i>.dss" ( const char *) rw

アリーナ <i>の、または <i>が "arenas.narenas"と等しいなら、すべてのアリーナの mmap 割り付けに関連づけられる dss 割り付けの優先順位を設定します。サポートされる設定については、"opt.dss"を参照してください。

"arenas.narenas" ( unsigned) r-

アリーナの数に関する現在の制限。

"arenas.initialized" ( bool *) r-

"arenas.narenas"ブール値の配列。各ブール値は、対応するアリーナが初期化されるかどうかを示します。

"arenas.quantum" ( size_t) r-

クオンタム (quantum) サイズ。

"arenas.page" ( size_t) r-

ページサイズ。

"arenas.tcache_max" ( size_t) r- [ --enable-tcache]

最大のスレッドにキャッシュされたサイズのクラス。

"arenas.nbins" ( unsigned) r-

bin サイズのクラスの数。

"arenas.nhbins" ( unsigned) r- [ --enable-tcache]

スレッドのキャッシュ bin サイズのクラスの合計数。

"arenas.bin.<i>.size" ( size_t) r-

サイズのクラスによってサポートされた最大のサイズ。

"arenas.bin.<i>.nregs" ( uint32_t) r-

ページ階級 (run) ごとの領域の数。

"arenas.bin.<i>.run_size" ( size_t) r-

ページ階級 (run) ごとのバイトの数。

"arenas.nlruns" ( size_t) r-

ラージ (large) サイズのクラスの合計数。

"arenas.lrun.<i>.size" ( size_t) r-

このラージサイズのクラスによってサポートされた最大のサイズ。

"arenas.purge" ( unsigned) -w

指定されたアリーナのための未使用のダーティページ、または none が指定されたなら、すべてのアリーナを消去します。

"arenas.extend" ( unsigned) r-

新しいアリーナを追加し、新しいアリーナのインデックスを返すことにより、アリーナの配列を拡張します。

"prof.active" ( bool) rw [ --enable-prof]

サンプリングが現在アクティブかどうかを制御します。追加情報については、 "opt.prof_active"オプションを参照してください。

"prof.dump" ( const char *) -w [ --enable-prof]

指定されたファイルへにメモリのプロファイルをダンプするか、または NULL が指定されるなら、パターン <prefix>.<pid>.<seq>.m<mseq>.heap に従ってファイルにダンプします、ここで、 <prefix>は、 "opt.prof_prefix"オプションによって制御されます。

"prof.interval" ( uint64_t) r- [ --enable-prof]

間隔に基づいたプロファイルのダンプの間に割り付けられたバイトの平均数。追加情報については、 "opt.lg_prof_interval"オプションを参照してください。

"stats.cactive" ( size_t *) r- [ --enable-stats]

アクティブなページのバイトの現在の数の近似のカウントを含んでいるカウンタへのポインタ。カウンタへのその貢献を計算するとき、各アリーナがチャンクサイズの最も近い倍数まで丸められるので、評価は、高いが低くないかもしれません。 "epoch" mallctl には、このカウンタと何も関係がないことに注意してください。さらに、カウンタの一貫性は、不可分の操作によって維持されるので、ポインタを逆参照するとき、一貫した読み込みを保証するために不可分の操作を使用することが必要です。

"stats.allocated" ( size_t) r- [ --enable-stats]

アプリケーションによって割り付けられたバイトの合計数。

"stats.active" ( size_t) r- [ --enable-stats]

アプリケーションによって割り付けられたアクティブなページのバイトの合計数。これは、ページサイズの倍数で、 "stats.allocated"以上です。

"stats.mapped" ( size_t) r- [ --enable-stats]

アプリケーションの代わりにマップされたチャンクのバイトの合計数。これは、チャンクサイズの倍数で、少なくとも "stats.active"と同じくらいの大きさです。これは、アクティブでないチャンクを含んでいません。

"stats.chunks.current" ( size_t) r- [ --enable-stats]

アプリケーションの代わりに活動的にマップされたチャンクの合計数。これは、アクティブでないチャンクを含んでいません。

"stats.chunks.total" ( uint64_t) r- [ --enable-stats]

割り付けられたチャンクの累積された数。

"stats.chunks.high" ( size_t) r- [ --enable-stats]

ここまでいつでもアクティブなチャンクの最大数、

"stats.huge.allocated" ( size_t) r- [ --enable-stats]

ヒュージオブジェクトによって現在割り付けられたバイトの数。

"stats.huge.nmalloc" ( uint64_t) r- [ --enable-stats]

ヒュージ割り付け要求の累積された数。

"stats.huge.ndalloc" ( uint64_t) r- [ --enable-stats]

ヒュージ割り付け解放要求の累積された数。

"stats.arenas.<i>.dss" ( const char *) r-

mmap(2) 割り付けに関連づけられる dss ( sbrk(2)) 割り付けの優先順位。詳細については、"opt.dss"を参照してください。

"stats.arenas.<i>.nthreads" ( unsigned) r-

アリーナに現在割り当てられたスレッドの数。

"stats.arenas.<i>.pactive" ( size_t) r-

アクティブな階級 (runs) のページの数。

"stats.arenas.<i>.pdirty" ( size_t) r-

潜在的にダーティな未使用の階級内のページの数、そして madvise ... MADV_DONTNEED のために、または呼び出されていない類似のもの。

"stats.arenas.<i>.mapped" ( size_t) r- [ --enable-stats]

マップされたバイトの数。

"stats.arenas.<i>.npurge" ( uint64_t) r- [ --enable-stats]

実行されたダーティページの消去されたスイープ (sweep) の数。

"stats.arenas.<i>.nmadvise" ( uint64_t) r- [ --enable-stats]

madvise ... MADV_DONTNEED の数、または消去されたダーティページに行われた同様の呼び出し。

"stats.arenas.<i>.npurged" ( uint64_t) r- [ --enable-stats]

消去されたページの数。

"stats.arenas.<i>.small.allocated" ( size_t) r- [ --enable-stats]

スモールオブジェクトによって現在割り付けられたバイトの数。

"stats.arenas.<i>.small.nmalloc" ( uint64_t) r- [ --enable-stats]

スモール bins によって役に立つ割り付け要求の累積された数。

"stats.arenas.<i>.small.ndalloc" ( uint64_t) r- [ --enable-stats]

bins に返されたスモールオブジェクトの累積された数。

"stats.arenas.<i>.small.nrequests" ( uint64_t) r- [ --enable-stats]

スモール割り付け要求の累積された数。

"stats.arenas.<i>.large.allocated" ( size_t) r- [ --enable-stats]

ラージオブジェクトによって現在割り付けられたバイトの数。

"stats.arenas.<i>.large.nmalloc" ( uint64_t) r- [ --enable-stats]

アリーナによって直接役に立つラージ割り付け要求の累積された数。

"stats.arenas.<i>.large.ndalloc" ( uint64_t) r- [ --enable-stats]

アリーナによって直接役に立つラージ割り付け解放要求の累積された数。

"stats.arenas.<i>.large.nrequests" ( uint64_t) r- [ --enable-stats]

ラージ割り付け要求の累積された数。

"stats.arenas.<i>.bins.<j>.allocated" ( size_t) r- [ --enable-stats]

bin によって割り付けられたバイトの現在の数。

"stats.arenas.<i>.bins.<j>.nmalloc" ( uint64_t) r- [ --enable-stats]

bin によって役に立つ割り付けの累積された数。

"stats.arenas.<i>.bins.<j>.ndalloc" ( uint64_t) r- [ --enable-stats]

bin に返された割り付けの累積された数。

"stats.arenas.<i>.bins.<j>.nrequests" ( uint64_t) r- [ --enable-stats]

割り付け要求の累積された数。

"stats.arenas.<i>.bins.<j>.nfills" ( uint64_t) r- [ --enable-stats --enable-tcache]

満たされた tcache の累積された数。

"stats.arenas.<i>.bins.<j>.nflushes" ( uint64_t) r- [ --enable-stats --enable-tcache]

フラッシュされた tcache の累積された数。

"stats.arenas.<i>.bins.<j>.nruns" ( uint64_t) r- [ --enable-stats]

作成された階級 (runs) の累積された数。

"stats.arenas.<i>.bins.<j>.nreruns" ( uint64_t) r- [ --enable-stats]

変更された割り付ける現在の階級 (run) の累積された数。

"stats.arenas.<i>.bins.<j>.curruns" ( size_t) r- [ --enable-stats]

階級 (runs) の現在の数。

"stats.arenas.<i>.lruns.<j>.nmalloc" ( uint64_t) r- [ --enable-stats]

アリーナによって直接役に立つ、このサイズのクラスのための割り付け要求の累積された数。

"stats.arenas.<i>.lruns.<j>.ndalloc" ( uint64_t) r- [ --enable-stats]

アリーナによって直接役に立つ、このサイズのクラスのための割り付け解放要求の累積された数。

"stats.arenas.<i>.lruns.<j>.nrequests" ( uint64_t) r- [ --enable-stats]

このサイズのクラスのための割り付け要求の累積された数。

"stats.arenas.<i>.lruns.<j>.curruns" ( size_t) r- [ --enable-stats]

このサイズのクラスのための階級 (runs) の累積された数。

MALLOC 問題のデバッグ

デバッグするとき、 --enable-debug--enable-fill オプションで jemalloc を設定/構築し、適切なオプションとデバッガサポートのためのシンボルでプログラムを再コンパイルすることはよい考えです。したがって、設定するとき、jemalloc は、double-free、write-after-free、などのようなアプリケーションエラーをキャッチする様々の実行時アサーションを組込みます。

プログラムは、0 バイトで実際に満たされている、“初期化されていない”メモリにしばしば偶然に依存します。ジャンク詰め物 ("opt.junk"オプション参照) は、明らかに正しくない結果および/またはコアダンプの形のそのようなバグをあらわにする傾向があります。反対に、0 の詰め物 ("opt.zero"オプション参照) は、そのようなバグの兆候を排除します。これらの 2 つのオプション間で、そのようなバグをすばやく検出し、診断し、排除するすることは通常可能です。

この実装は、そのような情報を格納するために性能の影響が抑制されるので、それが検出する問題に関する詳細を提供しません。しかしながら、jemalloc は、 --enable-valgrind 設定オプションが有効にされるなら、最も優れた m[blue] Valgrind[2] ツールで統合されます。

診断メッセージ

メモリ割り付け/割り付け解放関数のいずれかがエラーまたは警告の条件を検出するなら、メッセージは、ファイル記述子 STDERR_FILENO に印刷されます。エラーは、プロセスがコアをダンプする結果となります。 "opt.abort"オプションが設定されるなら、ほとんどの警告は、エラーとして扱われます。

malloc_message 変数によって、プログラマは、ある理由のために、 STDERR_FILENO ファイル記述子がこれに適していないなら、エラーと警告を書式化するテキスト文字列を出力する関数を上書きすることができます。 malloc_message は、文字列ポインタに続いて、 malloc_stats_print への呼び出しの引数によって上書きされないなら、 NULL である cbopaque ポインタ引数を取ります。この関数のメモリを割り付けを試みるものを行うことは、たぶんクラッシュまたはデッドロックの結果になることに注意してください。

すべてのメッセージは、“<jemalloc>:”が前に付けられます。

戻り値

標準 API

malloccalloc 関数は、成功するなら、割り付けられたメモリへのポインタを返します。そうでなければ、 NULL ポインタが返され、 errno は、 ENOMEM に設定されます。

posix_memalign 関数は、成功するなら、値 0 を返します。そうでなければ、それは、エラー値を返します。 posix_memalign 関数は、次の場合に失敗します:

EINVAL

alignment パラメータが、少なくとも sizeof( void *) と同じくらいの大きさで 2 のべき乗ではありません。

ENOMEM

メモリ割り付けエラー。

aligned_alloc 関数は、成功するなら、割り付けられたメモリへのポインタを返します。そうでなければ、 NULL ポインタが返され、 errno が設定されます。 aligned_alloc 関数は、次の場合に失敗します:

EINVAL

alignment パラメータが、2 のべき乗ではありません。

ENOMEM

メモリ割り付けエラー。

realloc 関数は、成功するなら、割り付けられたメモリへの (たぶん、 ptr と同一の) ポインタを返します。そうでなければ、 NULL ポインタが返され、エラーが割り付け失敗の結果であったなら、 errno は、 ENOMEM に設定されます。 realloc 関数は、エラーが生じるとき、常に元のバッファのままにしておきます。

free 関数は、値を返しません。

非標準 API

malloc_usable_size 関数は、 ptr によって指される割り付けの使用可能なサイズを返します。

mallctl, mallctlnametomibmallctlbymib 関数は、成功すれば、0 を返します。そうでなければ、それらは、エラー値を返します。関数は、次の場合に失敗します:

EINVAL

newpNULL ではなく、 newlen が大きすぎるか、または小さすぎます。また、 *oldlenp が大きすぎるか、または小さすぎます。この場合、データは、エラーにもかかわらずできるだけ読み込まれます。

ENOMEM

*oldlenp が要求された値を保持するためには短すぎます。

ENOENT

name または mib が、未知の値/無効の値を指定しています。

EPERM

無効の値を読み込むかまたは書き込を試みたか、または読み込み専用の値に書き込む試みをしました。

EAGAIN

メモリ割り付けの失敗が生じました。

EFAULT

副作用があるインタフェースが、 mallctl* 読み込み/書き込み処理と直接関係しないある方法に失敗しました。

実験的 API

allocmfR, rallocmfR, sallocmfR, dallocmfR と nallocmfR 関数は、成功すれば ALLOCM_SUCCESS を返します。そうでなければ、それらは、エラーの値を返します。 allocm, rallocmnallocm 関数は、次の場合に失敗します:

ALLOCM_ERR_OOM

メモリ不足。割り付け要求をサービスするために十分な連続するメモリを利用できませんでした。 allocm 関数は、さらに *ptrNULL に設定するのに対して、 rallocm 関数は、 *ptr 変更しないままとします。

また、 rallocm 関数は、次の場合に失敗します:

ALLOCM_ERR_NOT_MOVED

ALLOCM_NO_MOVE が指定されましたが、再割り付けの要求は、オブジェクトを移動させずにサービスすることができないかもしれません。

環境変数

次の環境変数は、割り付け関数の実行に影響します:

MALLOC_CONF

環境変数 MALLOC_CONF が設定されるなら、それが含んでいる文字は、オプションとして解釈されます。

使用例

問題が生じるときはいつでもコアダンプするためには:
 

ln -s 'abort:true' /etc/malloc.conf

16 MiB であるソースのチャンクサイズを指定するためには:

 

malloc_conf = "lg_chunk:24";

関連項目

madvise(2), mmap(2), sbrk(2), utrace(2), alloca(3), atexit(3), getpagesize(3)

規格

malloc, calloc, reallocfree 関数は、ISO/IEC 9899:1990 (“ISO C90”) に適合しています。

posix_memalign 関数は、IEEE Std 1003.1-2001 (“POSIX.1”) に適合しています。

歴史

malloc_usable_sizeposix_memalign 関数は、FreeBSD 7.0 ではじめて登場しました。

aligned_alloc, malloc_stats_print, mallctl**allocm 関数は、FreeBSD 10.0 ではじめて登場しました。

作者

Jason Evans

1.
jemalloc ウェブサイト
http://www.canonware.com/jemalloc/
2.
Valgrind
http://valgrind.org/
3.
gperftools パッケージ
http://code.google.com/p/gperftools/
06/02/2013 jemalloc 3.4.0-0-g0ed518e5dab7