MGL::Memory#

概要#

MGL::Memory名前空間にはMGLが使用するメモリアロケータに関わる定義・宣言が用意されています。これらの機能を利用することで、MGLが使用するアロケータを独自のアロケータに置き換えることが可能です。

MGLに独自のアロケータを設定する場合はメモリアロケータの作成（準備中）を参照してください。メモリアロケータを独自に設定しない場合は、MGLのデフォルトアロケータが使用されます。デフォルトアロケータの詳細についてはMGLのデフォルトアロケータを参照してください。

MGLが使用するアロケータはアプリケーション側からも利用可能ですが、その際には本項で解説する内容を直接扱うよりもSTLエイリアスの利用を推奨します。

型#

名前

内容

AllocatorType

アロケータの種類を表す型

定数#

名前

内容

値

kInvalidAllocatorType

無効なアロケータを表す値

説明参照

関数・定数式#

種類

名前

内容

定数式

MakeAllocatorType

メモリアロケータの種類を表す値を生成

関数

SetDefaultAllocator

デフォルトのメモリアロケータの設定

関数

SetAllocator

メモリアロケータの設定

関数

IsAvailableAllocator

メモリアロケータの有効状態を取得

関数

GetAllocatorType

メモリアロケータの種類を表す値を取得

関数

Allocate

メモリの確保

関数

Deallocate

メモリの解放

関数

GetSizeInfo

サイズ情報の取得

AllocatorType#

アロケータの種類を表す型

宣言#

namespace MGL::Memory
{
    enum class AllocatorType : uint32_t;
}

説明#

アロケータの種類を表す型です。各アロケータはこの型で表現された一意の値を持ち、外部からアロケータの種類を判別するために利用されます。

この値はMakeAllocatorTypeを利用して生成します。

関連#

kInvalidAllocatorType#

無効なアロケータを表す定数

宣言#

namespace MGL::Memory
{
    constexpr AllocatorType kInvalidAllocatorType = MakeAllocatorType("MGL-InvalidAllocator");
}

説明#

無効なアロケータを表す定数です。アロケータが未設定の状態でGetAllocatorTypeを呼び出した場合にこの値が返ります。

関連#

MakeAllocatorType#

メモリアロケータの種類を表す値を生成

宣言#

namespace MGL::Memory
{
    constexpr AllocatorType MakeAllocatorType(const char *key) noexcept;
}

引数#

const char *key

値の生成に利用する文字列

戻り値#

MGL::Memory::AllocatorType

文字列から生成された値

説明#

AllocatorTypeの値を生成するための定数式です。引数で指定した文字列を元に生成されます。

引数に指定する文字列は、利用する可能性のある他のアロケータと重複しない範囲で任意の文字列が利用可能です。先頭に"MGL-"が付く文字列はMGLが利用する可能性があるため避けてください。

利用例#

// 独自のアロケータ"YourAllocator"を表す値を生成
constexpr auto kYourAllocatorType = MGL::Memory::MakeAllocatorType("YourAllocatorName");

関連#

SetDefaultAllocator#

デフォルトのメモリアロケータの設定

宣言#

namespace MGL::Memory
{
    bool SetDefaultAllocator(const DefaultAllocator::Configuration &config) noexcept;
}

引数#

const MGL::Memory::DefaultAllocator::Configuration &config

デフォルトアロケータの設定パラメータ

戻り値#

bool

成功時にtrue、失敗時にfalse

説明#

MGLのデフォルトアロケータのパラメータを指定して設定します。

この関数は引数で指定されたパラメータでデフォルトアロケータを初期化し、初期化に成功した場合にそのアロケータをMGLに設定します。初期化に失敗した場合はfalseが返ります。

この関数はデフォルトアロケータをカスタマイズして使用する場合に呼び出す必要があります。デフォルトのパラメータを使用する場合はこの関数を呼び出す必要はありません。

詳細はMGLのデフォルトアロケータのコンフィギュレーションを参照してください。

利用例#

MGLのデフォルトアロケータのコンフィギュレーションを参照してください。

関連#

SetAllocator#

メモリアロケータの設定

宣言#

namespace MGL::Memory
{
    bool SetAllocator(Allocator *allocator) noexcept;
}

引数#

MGL::Memory::Allocator *allocator

設定するメモリアロケータ

戻り値#

bool

成功時にtrue、失敗時にfalse。

説明#

MGLが利用するメモリアロケータを設定します。

独自のメモリアロケータを利用したい場合、MGLの初期化前にこの関数を利用して設定してください。アロケータが設定されていない状態でMGL::Initializeが呼び出された場合、MGLのデフォルトのアロケータが自動で設定されます。

指定されたアロケータのIsInitializedがfalseを返す場合、この関数はInitializeを呼び出してアロケータの初期化を試みます。既に利用可能になっているアロケータを指定した場合は初期化を行いません。

メモリアロケータは一度設定を行うと、その後の変更は行えません。既に設定されている状態でこの関数を呼び出した場合、何もせずにfalseを返します。

MGLは引数で受けたアドレスのみを内部で保持し、内容のコピーは行いません。引数に指定するアロケータのインスタンスはアプリケーション動作中は常に有効である必要があります。

利用例#

// 独自のアロケータの準備。アプリケーション実行中は常に有効状態である必要がある。
static YourAllocator yourAllocator;

// 初期化は省略可。IsInitialized()がfalseを返す状態ならSetAllocator()が行う。
yourAllocator.Initialize();

// アロケータの設定。この呼び出しは MGLの初期化前に行う必要がある。
MGL::Memory::SetAllocator(&yourAllocator);

関連#

IsAvailableAllocator#

メモリアロケータの有効状態を取得

宣言#

namespace MGL::Memory
{
    bool IsAvailableAllocator() noexcept;
}

戻り値#

bool

アロケータが利用可能な場合はtrue、そうでなければfalse。

説明#

メモリアロケータの有効状態を取得します。有効なアロケータが設定されていない場合にfalseが返ります。

MGLは初期化時にこの関数を戻り値を参照し、必要に応じてデフォルトのアロケータを登録します。そのため、MGL初期化後には常にtrueが返ります。

利用例#

if (MGL::Memory::IsAvailableAllocator())
{
    // ここに到達する場合、アロケータが未設定
}

GetAllocatorType#

メモリアロケータの種類を表す値を取得

宣言#

namespace MGL::Memory
{
    AllocatorType GetAllocatorType() noexcept;
}

戻り値#

MGL::Memory::AllocatorType

設定中のメモリアロケータの種類を表す値

説明#

現在設定されているアロケータを表す値を取得します。アロケータが設定されていない場合はkInvalidAllocatorTypeが返ります。

利用例#

switch (MGL::Memory::GetAllocatorType())
{
    case MGL::Memory::DefaultAllocator::kAllocatorType:
        printf("デフォルトのアロケータを使用中\n");
        break;

    case MGL::Memory::kInvalidAllocatorType:
        printf("アロケータ未設定\n");
        break;

    default:
        printf("不明なアロケータを使用中\n");
        break;
}

関連#

Allocate#

メモリの確保

宣言#

namespace MGL::Memory
{
    [[nodiscard]] void *Allocate(size_t size) noexcept;
}

引数#

size_t size

要求サイズ

戻り値#

void *

確保したバッファの先頭アドレス。失敗時にはnullptr。

説明#

設定中のアロケータを利用してバッファを確保します。

アロケータが設定されていない状態では、この関数を呼び出すことはできません。MGL_DEBUGが定義されている場合はアサーションを行いますが、定義されていない場合は不正な参照を行います。

利用例#

// MGLのアロケータを経由して128バイトのバッファを確保
auto *buffer = reinterpret_cast<std::byte>(MGL::Memory::Allocate(128));

// 解放処理
MGL::Memory::Deallocate(buffer);


// アプリケーションから利用する場合はこちらを推奨
auto buffer2 = MGL::STL::make_unique<std::byte[]>(128);

関連#

Deallocate#

メモリの解放

宣言#

namespace MGL::Memory
{
    void Deallocate(void *buffer) noexcept;
}

引数#

void *buffer

解放するバッファのアドレス

説明#

Allocateで確保したメモリを解放します。引数にnullptrを指定した場合、この関数は何も行いません。

アロケータが設定されていない状態では、この関数を呼び出すことはできません。MGL_DEBUGが定義されている場合はアサーションを行いますが、定義されていない場合は不正な参照を行います。

利用例#

Allocateの利用例を参照してください。

関連#

GetSizeInfo#

サイズ情報の取得

宣言#

namespace MGL::Memory
{
    bool GetSizeInfo(size_t &dest, uint32_t key, uint32_t arg = 0) noexcept;
}

引数#

size_t &dest

取得したサイズ情報の格納先

uint32_t key

取得するサイズの種類を表すキー

uint32_t arg

取得の際に使用する引数。省略時は0。

戻り値#

bool

成功時にtrue、失敗時にfalse。

説明#

現在設定されているアロケータからサイズ情報を取得します。この関数は主にメモリの使用状況をモニタリングする際に利用します。

引数のkeyとargの内容は使用中のアロケータに依存します。MGLのデフォルトのアロケータが扱うサイズ情報についてはMGLのデフォルトアロケータのアロケータの使用状況の取得を参照してください。

取得に成功した場合は戻り値にtrueが返り、引数destに指定した変数に結果が格納されます。

利用例#

// MGLのデフォルトアロケータから malloc() / free() の利用状況を取得

// 利用中のアロケータがデフォルトのアロケータかをチェック
if (MGL::Memory::GetAllocatorType() != MGL::Memory::DefaultAllocator::kAllocatorType)
{
    // malloc() によって確保されているバッファの数を取得
    // この情報は MGL_DEBUG が定義されていない場合は取得に失敗する
    size_t systemUsedCount = 0;
    if (MGL::Memory::GetSizeInfo(systemUsedCount, MGL::Hash::FNV1a("SystemUsedCount")))
    {
        // malloc() によって確保されているバッファの合計サイズを取得
        size_t systemUsedSize = 0;
        if (MGL::Memory::GetSizeInfo(systemUsedSize, MGL::Hash::FNV1a("SystemUsedSize")))
        {
            printf("%zu : %zu\n", systemUsedSize, systemUsedCount);
        }
    }
}

関連#