MGL::Systemデバッグ用マクロ#

概要#

MGLのシステムアクセスにはデバッグ用モジュールが備わっており、この機能を呼び出すための各種プリプロセッサマクロが定義されています。

デバッグ用マクロはMGL_DEBUGマクロが定義されている場合にのみ有効化されます。MGLの標準構成で使用する限りにおいては、デバッグ用のビルド構成を用いることで自動的にMGL_DEBUGが定義され、各種デバッグ用マクロも利用可能となります。

MGL_DEBUGが定義されていない状況においては、デバッグ用マクロは空白へと置き換えられます。したがって、リリースビルド時にはこれらのマクロはソースコード上から削除されます。

注釈

これらの処理をリリースビルドに含めるべきではないという観点から、デバッグ用モジュールは他のシステムアクセスモジュールとは異なり、アクセサクラスを提供していません。

マクロ一覧#

種類	名前	内容	バージョン
マクロ	MGL_LOG	ログの出力	1.0.0+
マクロ	MGL_ERROR	エラーの出力	1.0.0+
マクロ	MGL_WARNING	警告の出力	1.0.0+
マクロ	MGL_TRACE	トレースの出力	1.0.0+
マクロ	MGL_LIBRARY_TRACE	ライブラリ向けトレースの出力	1.0.0+
マクロ	MGL_TRAP	再開可能なプロセスの中断	1.0.0+
マクロ	MGL_ABORT	再開不可能なプロセスの中断	1.0.0+
マクロ	MGL_ASSERT	アサーションマクロ	1.0.0+

MGL_LOG#

ログの出力

宣言#

#define MGL_LOG(logLevel, ...)

引数#

MGL::System::LogLevel logLevel: 出力するログの優先度を表す値

...: フォーマット文字列

説明#

デバッグ用のログを出力するためのマクロです。

引数logLevelにはログの優先度を表す値を指定し、続けて表示する文字列を指定します。文字列にはC言語の標準的なフォーマット指定が可能です。

ログレベルについてはMGL::System::LogLevelを参照してください。

ログの出力先は実行環境によって異なります。多くの場合、標準出力や標準エラー出力、デバッグ用の出力先などを対象とします。

通常はこのマクロをアプリケーション側から直接使用する必要はありません。各々のログレベルで出力するMGL_ERROR、MGL_WARNING、MGL_TRACE、MGL_LIBRARY_TRACEを使用してください。

利用例#

ログレベルAppTraceで"出力メッセージ"と表示する例

MGL_LOG(MGL::System::LogLevel::AppTrace, "出力メッセージ");

バージョン情報#

MGL 1.0.0から利用可能

MGL_ERROR#

エラーの出力

宣言#

#define MGL_ERROR(...)

引数#

...: フォーマット文字列

説明#

デバッグ用のエラーログを表示するためのマクロです。このログの出力にはMGL::System::LogLevelにおけるErrorが使用されます。

エラーメッセージ最も重要度の高い異常を通知する際に出力すべきメッセージです。継続困難な状況やその後の動作に支障をきたす場合など、致命的な状況を伝える場合に使用してください。

引数には表示する文字列を指定します。この文字列にはC言語の標準的なフォーマット指定が可能です。

ログの出力先は実行環境によって異なります。多くの場合、標準出力や標準エラー出力、デバッグ用の出力先などを対象とします。

利用例#

ログの出力先にエラーメッセージを出力する例

MGL_ERROR("エラーメッセージ");

バージョン情報#

MGL 1.0.0から利用可能

MGL_WARNING#

警告の出力

宣言#

#define MGL_WARNING(...)

引数#

...: フォーマット文字列

説明#

デバッグ用の警告ログを表示するためのマクロです。このログの出力にはMGL::System::LogLevelにおけるWarningが使用されます。

警告メッセージは致命的ではないが対処を強く推奨する場合に出力すべきメッセージです。通常、開発者は警告もエラーと同等に対処すべき問題として認識します。

引数には表示する文字列を指定します。この文字列にはC言語の標準的なフォーマット指定が可能です。

ログの出力先は実行環境によって異なります。多くの場合、標準出力や標準エラー出力、デバッグ用の出力先などを対象とします。

利用例#

ログの出力先に警告メッセージを出力する例

MGL_WARNING("警告メッセージ");

バージョン情報#

MGL 1.0.0から利用可能

MGL_TRACE#

トレースの出力

宣言#

#define MGL_TRACE(...)

引数#

...: フォーマット文字列

説明#

デバッグ用のトレースを表示するためのマクロです。このログの出力にはMGL::System::LogLevelにおけるAppTraceが使用されます。

トレースメッセージは処理の流れを可視化する場合など、実装の都合で何かを確認すべき場合に使用するメッセージです。その用途は開発者に委ねられていますが、多くの開発者は（必要に迫られない限りは）この出力を重要な情報として扱わないでしょう。

引数には表示する文字列を指定します。この文字列にはC言語の標準的なフォーマット指定が可能です。

ログの出力先は実行環境によって異なります。多くの場合、標準出力や標準エラー出力、デバッグ用の出力先などを対象とします。

利用例#

ログの出力先にトレース出力する例

MGL_TRACE("トレースメッセージ");

バージョン情報#

MGL 1.0.0から利用可能

MGL_LIBRARY_TRACE#

ライブラリ向けトレースの出力

宣言#

#define MGL_LIBRARY_TRACE(...)

引数#

...: フォーマット文字列

説明#

デバッグ用のエラーログを表示するためのマクロです。このログの出力にはMGL::System::LogLevelにおけるLibraryTraceが使用されます。

ライブラリ向けのトレース出力はMGL自身やそのエクステンションなど、バックエンド向けのトレース出力を行う際に使用します。このログレベルは最も優先度が低く設定されており、意図的に指定しない限りはアプリケーション側の開発者の目に触れることのない出力となっています。

引数には表示する文字列を指定します。この文字列にはC言語の標準的なフォーマット指定が可能です。

ログの出力先は実行環境によって異なります。多くの場合、標準出力や標準エラー出力、デバッグ用の出力先などを対象とします。

利用例#

ログの出力先にライブラリ向けのトレースを出力する例

MGL_LIBRARY_TRACE("トレースメッセージ");

バージョン情報#

MGL 1.0.0から利用可能

MGL_TRAP#

再開可能なプロセスの中断

宣言#

#define MGL_TRAP()

説明#

処理を一時的に停止させるためのマクロです。

プログラムの実行がこのマクロの位置に到達した際に、可能であれば処理を中断してデバッガへと制御を移します。このマクロで停止したプロセスはデバッガから再開可能です。

アプリケーションがデバッガにアタッチしていない場合や、実行環境が処理の中断に対応していない場合など、中断が不可能な状況ではこのマクロは使用できません。

利用例#

トラップの呼び出し例

MGL_TRAP();

バージョン情報#

MGL 1.0.0から利用可能

MGL_ABORT#

再開不可能なプロセスの中断

宣言#

#define MGL_ABORT()

説明#

プログラムを完全に中断します。この処理が呼び出された際の挙動はシステム依存ですが、多くのシステムではクラッシュダンプを生成してアプリケーションを強制終了させます。

条件とエラーログを必要とするアボート処理にはMGL_ASSERTを使用してください。

利用例#

アボートの呼び出し例

MGL_ABORT();

バージョン情報#

MGL 1.0.0から利用可能

MGL_ASSERT#

アサーションマクロ

宣言#

#define MGL_ABORT(expr, ...)

引数#

bool expr: アサーションの条件

...: エラーログとして表示する文字列

説明#

プログラミングにおけるアサーション（表明）は、その処理を行うための前提条件を設定しておき、それを満たさない状況を検出するための手法です。このマクロは前提条件を設定し、条件を満たさない場合にエラーメッセージの表示とプログラムの中断を行います。

引数exprには前提条件となる式を指定します。この式の結果はbool型へとキャストされ、値がfalseだった場合は表明違反とみなしてプログラムを中断します。中断にはMGL_ABORTと同等の処理が使用されます。

第2引数にはエラーログとして表示する文字列を指定します。このログの性質はMGL_ERRORと同等です。

ヒント

C++は言語仕様として静的アサーションstatic_assertも備えています。コンパイル時に静的に判別可能なアサーションについてはこちらを使用してください。

利用例#

NULLポインタを受け付けない関数にアサーションを仕込む例

void AnyProcess(void *argument)
{
    MGL_ASSERT(argument, "argument が NULL です");

    ...
}

注釈

ポインタ変数をbool型に変換した場合、その内容がnullptrであればfalseに、そうでなければtrueに変換されます。したがって、ポインタ変数をそのままアサーションの条件式に渡すことによって、その変数がNULLではない事への表明となります。

バージョン情報#

MGL 1.0.0から利用可能

MGLドキュメント

MGL::System デバッグ用マクロ

Contents

MGL::Systemデバッグ用マクロ#

概要#

マクロ一覧#

MGL_LOG#

宣言#

引数#

説明#

利用例#

バージョン情報#

関連#

MGL_ERROR#

宣言#

引数#

説明#

利用例#

バージョン情報#

関連#

MGL_WARNING#

宣言#

引数#

説明#

利用例#

バージョン情報#

関連#

MGL_TRACE#

宣言#

引数#

説明#

利用例#

バージョン情報#

関連#

MGL_LIBRARY_TRACE#

宣言#

引数#

説明#

利用例#

バージョン情報#

関連#

MGL_TRAP#

宣言#

説明#

利用例#

バージョン情報#

関連#

MGL_ABORT#

宣言#

説明#

利用例#

バージョン情報#

関連#

MGL_ASSERT#

宣言#

引数#

説明#

利用例#

バージョン情報#

関連#