名称

libmemstat — カーネルメモリアロケータ統計値を検索するライブラリインタフェース

ライブラリ

Kernel Memory Allocator Statistics Library (libmemstat, -lmemstat)

書式

#include < sys/types.h>
#include < memstat.h>

一般的関数

const char *
memstat_strerror( int error);

メモリタイプリスト管理関数

struct memory_type_list *
memstat_mtl_alloc( void);

struct memory_type *
memstat_mtl_first( struct memory_type_list *list);

struct memory_type *
memstat_mtl_next( struct memory_type *mtp);

struct memory_type *
memstat_mtl_find( struct memory_type_list *list, int allocator, const char *name);

void
memstat_mtl_free( struct memory_type_list *list);

int
memstat_mtl_geterror( struct memory_type_list *list);

アロケータ問い合わせ関数

int
memstat_kvm_all( struct memory_type_list *list, void *kvm_handle);

int
memstat_kvm_malloc( struct memory_type_list *list, void *kvm_handle);

int
memstat_kvm_uma( struct memory_type_list *list, void *kvm_handle);

int
memstat_sysctl_all( struct memory_type_list *list, int flags);

int
memstat_sysctl_malloc( struct memory_type_list *list, int flags);

int
memstat_sysctl_uma( struct memory_type_list *list, int flags);

メモリタイプアクセサ方式

const char *
memstat_get_name( const struct memory_type *mtp);

int
memstat_get_allocator( const struct memory_type *mtp);

uint64_t
memstat_get_countlimit( const struct memory_type *mtp);

uint64_t
memstat_get_byteslimit( const struct memory_type *mtp);

uint64_t
memstat_get_sizemask( const struct memory_type *mtp);

uint64_t
memstat_get_size( const struct memory_type *mtp);

uint64_t
memstat_get_memalloced( const struct memory_type *mtp);

uint64_t
memstat_get_memfreed( const struct memory_type *mtp);

uint64_t
memstat_get_numallocs( const struct memory_type *mtp);

uint64_t
memstat_get_numfrees( const struct memory_type *mtp);

uint64_t
memstat_get_bytes( const struct memory_type *mtp);

uint64_t
memstat_get_count( const struct memory_type *mtp);

uint64_t
memstat_get_free( const struct memory_type *mtp);

uint64_t
memstat_get_failures( const struct memory_type *mtp);

void *
memstat_get_caller_pointer( const struct memory_type *mtp, int index);

void
memstat_set_caller_pointer( struct memory_type *mtp, int index, void *value);

uint64_t
memstat_get_caller_uint64( const struct memory_type *mtp, int index);

void
memstat_set_caller_uint64( struct memory_type *mtp, int index, uint64_t value);

uint64_t
memstat_get_zonefree( const struct memory_type *mtp);

uint64_t
memstat_get_kegfree( const struct memory_type *mtp);

uint64_t
memstat_get_percpu_memalloced( const struct memory_type *mtp, int cpu);

uint64_t
memstat_get_percpu_memfreed( const struct memory_type *mtp, int cpu);

uint64_t
memstat_get_percpu_numallocs( const struct memory_type *mtp, int cpu);

uint64_t
memstat_get_percpu_numfrees( const struct memory_type *mtp, int cpu);

uint64_t
memstat_get_percpu_sizemask( const struct memory_type *mtp, int cpu);

void *
memstat_get_percpu_caller_pointer( const struct memory_type *mtp, int cpu, int index);

void
memstat_set_percpu_caller_pointer( struct memory_type *mtp, int cpu, int index, void *value);

uint64_t
memstat_get_percpu_caller_uint64( const struct memory_type *mtp, int cpu, int index);

void
memstat_set_percpu_caller_uint64( struct memory_type *mtp, int cpu, int index, uint64_t value);

uint64_t
memstat_get_percpu_free( const struct memory_type *mtp, int cpu);

解説

libmemstat は、デバッグとシステムの監視の目的のために、アロケータの実装細部からアプリケーションを分離して、ツールが透過的に複数のアロケータをサポートできる、カーネルメモリアロケータ統計を検索するためのインタフェースを提供します。 libmemstat は、長期のモニタで徐々に増える統計の更新と同様に、単一の統計スナップショットの検索の両方をサポートします。

libmemstat は、ライブラリ中のアクセス関数を使用してアプリケーションによってアクセスされる struct memory_type を使用して各メモリタイプを説明します。 libmemstat は、 memstat_mtl_alloc() 呼び出すことによって割り付けられ memstat_mtl_free() を使用して完全に解放される、 struct memory_type_list を通して struct memory_type のチェーンを返して更新します。メモリタイプのリストは、統計情報をカーネルに問い合わせる呼び出しを通して使用できます、現在は次の通りです: memstat_kvm_all(), memstat_kvm_malloc(), memstat_kvm_uma(), memstat_sysctl_all(), memstat_sysctl_uma() と memstat_sysctl_malloc()。繰り返される呼び出しは、すべてのリスト状態を再作成することなしに、時間とともに追跡できる、メモリタイプのリストを増加して更新します。エラーが問い合わせ呼び出しの間に検出されるなら、エラー条件情報は、 memstat_mtl_geterror() を使用して検索され、 memstat_strerror() を使用してユーザが読める文字列に変換されます。

リストを解放することは、リスト中のすべてのメモリタイプデータを解放するので、リスト中のエントリを指す任意の未解決のポインタを無効にします。リスト中の struct memory_type は、それぞれ、リスト中の最初のエントリを返す memstat_mtl_first() と、リスト中の次のエントリを返す memstat_mtl_next() を使用して繰り返されます。 memstat_mtl_find(), は、渡されたパラメータに適合する最初のエントリへのポインタを返します。

呼び出し側に所有されているフィールドの設定と同様に、統計と特性 (プロパティ) を検索することを含んで、構造体のフィールドにアクセスするための一連のアクセス方式を提供します。アプリケーションがデータ構造体フィールドに直接アクセスすることは、サポートされていません。

ライブラリ memory_type Ss フィールド

各 struct memory_type は、使用時の現在の統計と同様に、それが管理される名前とアロケータを含んで、メモリタイプの説明を保持しています。いくつかの統計は直接測定され、他は直接測定された統計から得られます。特定のハイレベルな統計は、割り付けと解放の操作の数のような、すべての利用可能なアロケータにわたって存在しています。 CPU 毎のキャッシュにおける解放項目の量、または割り付けの数における管理制限などの、他の測定値は、特定のアロケータだけで利用可能です。

呼び出し側 memory_type Ss フィールド

struct memory_type は、メモリタイプに従ってポインタと 64 ビットの整数の形式で、アプリケーションがデータを格納することができるフィールドを含んでいます。例えば、アプリケーションの作者は、メモリタイプの長い期間の振る舞いを追跡するより複雑なデータ構造体を参照する呼び出し側のポインタの 1 つ、またはメモリタイプの状態をレンダリング (表示) するために使用されるウィンドウシステムオブジェクトを使用するかもしれません。一般的で CPU 毎の記憶域は、ポインタと整数の配列の形式で、それぞれ struct memory_type で提供されます。配列エントリは、アクセス方式を取得して設定するための index 引数を通してアクセスされます。 index の取り得る値は、 0 と MEMSTAT_MAXCALLER の間の範囲です。

呼び出し側によって所有されているフィールドは、新しい struct memory_type が割り付けられメモリタイプにアタッチされるとき、 0 または NULL に初期化されます。これらのフィールドは、ライブラリによって所有されているフィールドを更新する問い合わせのあいだも、それらの値を持ち続けます。

アロケータタイプ

現在、 libmemstat は、2 つのカーネルアロケータをサポートします: uma(9) のための ALLOCATOR_UMA、と malloc(9) のための ALLOCATOR_MALLOC です。これらの値は、 memstat_mtl_find() に渡され、 memstat_get_allocator() によって返されます。アロケータ名前スペースの 2 つの追加定数は、次のように定義されます: ライブラリエラーの結果として返されるだけの、 ALLOCATOR_UNKNOWN と任意のアロケータに適合する返されたタイプが、 memstat_mtl_find() から許可可能であると指定するために使用することができる ALLOCATOR_ANY です。

アクセス方式リスト

与えられたメモリタイプのために有効となる次のアクセス方式が定義されています:

memstat_get_name(): メモリタイプの名前を指すポインタを返します。名前のためのメモリは、 libmemstat によって所有され、 memstat_mtl_free() への呼び出しで有効となります。名前は、単一のアロケータに関してユニークになりますが、同じ名前が異なったメモリアロケータによって所有されている異なったメモリタイプによって使用されるかもしれないことに注意してください。
memstat_get_allocator(): メモリタイプを所有しているメモリアロケータのための整数識別子を返します。
memstat_get_countlimit(): メモリタイプが同時に割り付ける数に管理制限があるなら、それを返します。
memstat_get_byteslimit(): メモリタイプがメモリタイプのために同時に割り付けられるメモリのバイト数に管理制限があるなら、それを返します。
memstat_get_sizemask(): メモリタイプが可変の割り付けサイズをサポートするなら、メモリタイプのために割り付けられたサイズのビットマスクを返します。
memstat_get_size(): メモリタイプが固定の割り付けサイズをサポートするなら、そのサイズを返します。
memstat_get_memalloced(): 存続期間のうちにメモリタイプのために割り付けられたバイトの合計数を返します。
memstat_get_memfreed(): 存続期間のうちにメモリタイプのために解放されたバイトの合計数を返します。
memstat_get_numallocs(): 存続期間のうちにメモリタイプのための割り付けの合計数を返します。
memstat_get_numfrees(): 存続期間のうちにメモリタイプのための解放の合計数を返します。
memstat_get_bytes(): メモリタイプに割り付けられた現在のバイト数を返します。
memstat_get_count(): メモリタイプのための割り付けの現在の数を返します。
memstat_get_free(): メモリアロケータがキャッシュをサポートするなら、キャッシュ中の項目の数を返します。
memstat_get_failures(): メモリアロケータとタイプが割り付けの失敗を許すなら、測定された割り付け失敗の数を返します。
memstat_get_caller_pointer(): メモリタイプのために呼び出し側によって所有されているポインタを返します。
memstat_set_caller_pointer(): メモリタイプのために呼び出し側によって所有されているポインタを設定します。
memstat_get_caller_uint64(): メモリタイプのために呼び出し側によって所有されている整数を返します。
memstat_set_caller_uint64(): メモリタイプのために呼び出し側によって所有されている整数を設定します。
memstat_get_zonefree(): メモリアロケータがマルチレベル割り付け構造体をサポートするなら、ゾーン中にキャッシュされた項目の数を返します。これらの項目は、直ちに使用するために完全に構築され利用可能な状態となります。
memstat_get_kegfree(): メモリアロケータがマルチレベル割り付け構造体をサポートするなら、 keg のキャッシュされた項目の数を返します。これらの項目は、部分的に構築された状態になって、それらを利用可能にすることができる前に、それ以上の処理を必要とします。
memstat_get_percpu_memalloced(): メモリアロケータが CPU ごとの統計をサポートするなら、存続期間のうちに CPU のメモリタイプのために割り付けられたメモリのバイト数を返します。
memstat_get_percpu_memfreed(): メモリアロケータが CPU ごとの統計をサポートするなら、存続期間のうちに CPU のメモリタイプから解放されたメモリのバイト数を返します。
memstat_get_percpu_numallocs(): メモリアロケータが CPU ごとの統計をサポートするなら、存続期間のうちに CPU のメモリタイプのための割り付けの数を返します。
memstat_get_percpu_numfrees(): メモリアロケータが CPU ごとの統計をサポートするなら、存続期間のうちに CPU のメモリタイプのための解放の数を返します。
memstat_get_percpu_sizemask(): メモリアロケータが可変サイズメモリ割り付けと CPU ごとの統計をサポートするなら、CPU のメモリタイプのためのサイズビットマスクを返します。
memstat_get_percpu_caller_pointer(): メモリタイプのための呼び出し側によって所有されている CPU ごとのポインタを返します。
memstat_set_percpu_caller_pointer(): メモリタイプのための呼び出し側によって所有されている CPU ごとのポインタを設定します。
memstat_get_percpu_caller_uint64(): メモリタイプのための呼び出し側によって所有されている CPU ごとの整数を返します。
memstat_set_percpu_caller_uint64(): メモリタイプのための呼び出し側によって所有されている CPU ごとの整数を設定します。
memstat_get_percpu_free(): メモリアロケータが CPU ごとのキャッシュをサポートするなら、指定された CPU の CPU ごとのキャッシュにおける解放項目の数を返します。

戻り値

libmemstat 関数は 3 つのカテゴリに分類されます: オブジェクトへのポインタを返す関数、整数の戻り値を返す関数、と struct memory_type からデータを返すアクセス方式を実装する関数。

一般的に、オブジェクトへのポインタを返す関数は、失敗するとき NULL を返します。 memstat_mtl_alloc() は、値 ENOMEM から成る errno を通してエラー値を返します。関数 memstat_mtl_first(), memstat_mtl_next() と memstat_mtl_find() は、エントリがないか、または次のリストに適合するとき、 NULL を返します。しかしながら、これは失敗モードであるとみなされず、エラー値は利用可能ではありません。

整数の戻り値を返す関数は、成功すれば 0 を返すか、または失敗すれば-1 を返します。失敗が返えされるなら、リストエラーアクセス方式 memstat_mtl_geterror() は、エラー状態を検索するために使用されます。エラーの文字列表現は、 memstat_strerror() を使用して検索されます。起こり得るエラー値は次の通りです:

最終に、 struct memory_type ポインタからデータを返す関数は、失敗することは許されず、統計値か文字列へのポインタのいずれかを直接返します。

使用例

メモリタイプリストを作成し、利用可能な統計のための uma(9) メモリアロケータについて問い合わせをおこない、そして、 mbuf ゾーンによって実行された割り付けの数を印刷 (表示) します。

struct memory_type_list *mtlp; 
struct memory_type *mtp; 
uint64_t mbuf_count; 
 
mtlp = memstat_mtl_alloc(); 
if (mtlp == NULL) 
    err(-1, "memstat_mtl_alloc"); 
if (memstat_sysctl_uma(mtlp, 0) < 0) 
    err(-1, "memstat_sysctl_uma"); 
mtp = memstat_mtl_find(mtlp, ALLOCATOR_UMA, "mbuf"); 
if (mtp == NULL) 
    errx(-1, "memstat_mtl_find: mbuf not found"); 
mbuf_count = memstat_get_count(mtp); 
memstat_mtl_free(mtlp); 
 
printf("mbufs: %llu\n", (unsigned long long)mbuf_count);

歴史

libmemstat ライブラリは、 FreeBSD 6.0 で登場しました。

作者

汎用のモニタリングライブラリをサポートするために必要なカーネルメモリアロケータの変更は、ライブラリとともに、 Robert Watson <rwatson@FreeBSD.org>によって書かれました。

バグ

カーネルには、現在、 libmemstat によってサポートされていない、VM ページアロケータや sf_buf アロケータなどのような、メモリアロケータがあります。

いったん、メモリタイプがメモリタイプリストに存在しているなら、カーネルがインタフェースをモニタすることを通してタイプに情報がすでに存在しなくても、それを取り除きません。取り除かれたメモリタイプをフラッシュするために、全体のリストを解放して、新しいものを割り付けることが必要です。

YOS OPENSONAR

名称