スケーラブル・アロケーターの C インターフェイス

概要

スケーラブルなメモリー割り当て用の低水準インターフェイス。

構文

extern "C" {
    // C メモリー・アロケーターのスケーラブル・バージョン
    void* scalable_malloc( size_t size );
    void  scalable_free( void* ptr );
    void* scalable_calloc( size_t nobj, size_t size );
    void* scalable_realloc( void* ptr, size_t size );

    // _msize/malloc_size/malloc_usable_size バージョン
    size_t scalable_msize( void* ptr );

    // posix_memalign のスケーラブル・バージョン
    int scalable_posix_memalign( void** memptr, size_t alignment, size_t size );

    // アライメントされた割り当て
    void* scalable_aligned_malloc( size_t size, size_t alignment);
    void scalable_aligned_free( void* ptr ); 
    void* scalable_aligned_realloc( void* ptr, size_t size, size_t alignment );

    // scalable_allocation_* 関数の戻り値
    typedef enum {
        TBBMALLOC_OK,
        TBBMALLOC_INVALID_PARAM,
        TBBMALLOC_UNSUPPORTED,
        TBBMALLOC_NO_MEMORY,
        TBBMALLOC_NO_EFFECT
    } ScalableAllocationResult;

    typedef enum {
        // ラージ・メモリー・ページの使用のオン/オフ
        TBBMALLOC_USE_HUGE_PAGES,
        // アロケーターのメモリー使用量のしきい値を設定
        // しきい値を超えたら内部メモリーバッファーをクリーン
        TBBMALLOC_SET_SOFT_HEAP_LIMIT
    } AllocationModeParam;

    // アロケーター固有のアロケーション・モードを設定
    int scalable_allocation_mode(int param, intptr_t value);

    typedef enum {
        // すべてのスレッドの内部アロケーター・バッファーをクリーン
        TBBMALLOC_CLEAN_ALL_BUFFERS,
        // 現在のスレッドの内部アロケーター・バッファーをクリーン
        TBBMALLOC_CLEAN_THREAD_BUFFERS
    } ScalableAllocationCmd;

    // アロケーター固有のコマンドを呼び出す
    int scalable_allocation_command(int cmd, void *param);
}

ヘッダー

#include "tbb/scalable_allocator.h"

説明

これらの関数は、スケーラブル・アロケーターに C 水準のインターフェイスを提供します。scalable_allocation_mode および scalable_allocation_command を除き、scalable_x ルーチンはそれぞれ、x ライブラリー関数に似た動作を行います。下記の表に示されているように、ルーチンには 2 つのファミリーがあります。あるファミリーの scalable_x 関数で割り当てた記憶領域は、C 標準ライブラリー関数ではなく、同じファミリーの scalable_x 関数で解放またはサイズ変更してください。同様に、C 標準ライブラリー関数で割り当てた記憶領域は、scalable_x 関数で解放またはサイズ変更しないでください。

スケーラブル・アロケーターの C インターフェイス

ファミリー

割り当てルーチン

割り当て解除ルーチン

類似ライブラリー

1

scalable_malloc

scalable_free

C 標準ライブラリー

scalable_calloc

scalable_realloc

scalable_posix_memalign

POSIX*

2

scalable_aligned_malloc

scalable_aligned_free

Microsoft* C ランタイム・ライブラリー

scalable_aligned_realloc

次の関数は、メモリーの割り当て/解放は行いませんが、メモリー・アロケーターに関する有用な情報を取得し、その動作に影響を与えることができます。

size_t scalable_msize( void* ptr )

戻り値: スケーラブル・アロケーターで割り当てられた場合、ptr が指し示すメモリーブロックの使用可能なサイズ。ptr がそのようなブロックを指していない場合は 0。

int scalable_allocation_mode(int mode, intptr_t value)

この関数は、スケラーブル・メモリー・アロケーターの動作を調整するために使用されます。

戻り値: 操作に成功した場合は TBBMALLOC_OK。mode が次のいずれかでない、または value が指定されたモードで有効でない場合は TBBMALLOC_INVALID_PARAM。次に示すように、ほかの戻り値も可能です。

引数 説明
TBBMALLOC_USE_HUGE_PAGES

scalable_allocation_mode(TBBMALLOC_USE_HUGE_PAGES, 1) は、オペレーティング・システムでラージページが有効に設定されている場合、アロケーターにその使用を指示します。scalable_allocation_mode(TBBMALLOC_USE_HUGE_PAGES, 0) は無効にします。TBB_MALLOC_USE_HUGE_PAGES 環境変数を 1 に設定すると scalable_allocation_mode(TBBMALLOC_USE_HUGE_PAGES, 1) と同じ効果が得られます。scalable_allocation_mode() で設定されたモードは環境変数よりも優先されます。

戻り値: 大容量ページがプラットフォームでサポートされていない場合は TBBMALLOC_NO_EFFECT。

現時点では、この割り当てモードは Linux* でのみサポートされています。明示的に設定されたラージページと透過的なラージページの両方で動作します。

注意

このモードでは、メモリー要求サイズまたはアライメントを大容量ページサイズの倍数に丸めることは推奨しません。大容量ページが効率良く使用されず、パフォーマンスが低下する可能性があります。

TBBMALLOC_SET_SOFT_HEAP_LIMIT

scalable_allocation_mode(TBBMALLOC_SET_SOFT_HEAP_LIMIT, size) は、アロケーターが OS から取得するメモリー量のしきい値 size (バイト単位) を設定します。しきい値を超えると、アロケーターの内部バッファーからメモリーを解放しますが、必要な場合により多くのメモリーを要求することを阻むわけではありません。

int scalable_allocation_command(int cmd, void *reserved)

この関数は、第 1 引数で指定された動作を実行するようスケーラブル・メモリー・アロケーターに指示するために使用されます。第 2 引数は予約されています。0 に設定してください。

戻り値: 操作に成功した場合は TBBMALLOC_OK。cmd が次のいずれかでない、または reserved が 0 でない場合は TBBMALLOC_INVALID_PARAM。

引数 説明
TBBMALLOC_CLEAN_ALL_BUFFERS

scalable_allocation_command(TBBMALLOC_CLEAN_ALL_BUFFERS, 0) は、アロケーターの内部メモリーバッファーをクリーンして、メモリーのフットプリントを減らします。その結果、後続のメモリー割り当てリクエストにかかる時間は増えます。このコマンドは頻繁に使用されることを想定していません。パフォーマンスに与える影響を慎重に評価することを推奨します。

戻り値: バッファーが解放されなかった場合は TBBMALLOC_NO_EFFECT。

呼び出しがすべての未使用メモリーを解放することは保証されません。

TBBMALLOC_CLEAN_THREAD_BUFFERS

scalable_allocation_command(TBBMALLOC_CLEAN_THREAD_BUFFERS, 0) は、呼び出しスレッドの内部メモリーバッファーをクリーンします。その結果、後続のメモリー割り当てリクエストにかかる時間は増えます。パフォーマンスに与える影響を慎重に評価することを推奨します。

戻り値: バッファーが解放されなかった場合は TBBMALLOC_NO_EFFECT。