Exception.h

[詳解]

/// @file
/// @brief AM Daemon の例外クラス Exception のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_EXCEPTION_H
#define AMDAEMON_EXCEPTION_H

#include "amdaemon/env.h"
#include "amdaemon/ExceptionCategory.h"
#include "amdaemon/util/misc.h"

#include <exception>
#include <vector>
#include <memory>

#if AMDAEMON_ON_MSVC
#include <crtdefs.h> // for __FILEW__
#endif // AMDAEMON_ON_MSVC

namespace amdaemon
{
    // 前方宣言
    namespace util { class StackTrace; }

/// @addtogroup g_exception
/// @{

    /// @brief AM Daemon の例外クラス。
    ///
    /// 既定ではライブラリ内で例外が発生するとこのクラスのインスタンスがスローされる。
    ///
    /// C++標準の例外情報に加え、例外発生位置やスタックトレースの情報を保持している。
    /// メンバ関数 #toString によりそれらの情報をまとめて文字列化できる。
    ///
    /// Core クラスのメンバ関数
    /// Core#setExceptionHook を用いてライブラリに例外フック関数を設定することで、
    /// 例外をスローさせる代わりにこのクラスのインスタンスを受け取って処理することができる。
    /// 例外をスローしないようにすることもでき、
    /// その場合のライブラリ側の挙動は例外カテゴリに依存する。
    /// 詳細は各 @ref ExceptionCategory 列挙値の説明を参照すること。
    class Exception : public std::exception
    {
    public:
        /// @brief コンストラクタ。
        /// @param[in] category 例外カテゴリ。
        /// @param[in] file 例外発生時のファイル名。不明ならば nullptr 。
        /// @param[in] line 例外発生時のファイル行番号。不明ならば負数。
        /// @param[in] func 例外発生時の関数名。不明ならば nullptr 。
        /// @param[in] message 例外発生時の付随メッセージ。無いならば nullptr 。
        /// @param[in] whatFile 例外メッセージ用のファイル名。不明ならば nullptr 。
        /// @param[in] whatFunc 例外メッセージ用の関数名。不明ならば nullptr 。
        ///
        /// 通常、このコンストラクタを直接呼び出すことはなく、
        /// AMDAEMON_MAKE_EXCEPTION マクロまたは AMDAEMON_MAKE_EXCEPTION_MSG マクロを
        /// 用いてインスタンスを生成するか、
        /// AMDAEMON_RAISE_EXCEPTION マクロまたは AMDAEMON_RAISE_EXCEPTION_MSG マクロを
        /// 用いて例外を発生させる。
        Exception(
            ExceptionCategory category,
            const wchar_t* file,
            int line,
            const wchar_t* func,
            const wchar_t* message,
            const char* whatFile,
            const char* whatFunc);

        /// @brief コピーコンストラクタ。
        /// @param[in] src コピー元。
        Exception(const Exception& src);

        /// @brief ムーブコンストラクタ。
        /// @param[in] src ムーブ元。
        Exception(Exception&& src);

        /// デストラクタ。
        ‾Exception() throw();

        /// @brief コピー代入演算子のオーバロード。
        /// @param[in] r 右辺値。
        /// @return 自身の参照。
        Exception& operator=(const Exception& r);

        /// @brief ムーブ代入演算子のオーバロード。
        /// @param[in] r 右辺値。
        /// @return 自身の参照。
        Exception& operator=(Exception&& r);

        /// @brief 例外文字列を取得する。
        /// @return 例外文字列。
        const char* what() const override;

        /// @brief 例外カテゴリを取得する。
        /// @return 例外カテゴリ。不明ならば ExceptionCategory::Unknown 。
        ExceptionCategory getCategory() const;

        /// @brief 例外発生時のファイル名を取得する。
        /// @return 例外発生時のファイル名。不明ならば空文字列。
        const wchar_t* getFile() const;

        /// @brief 例外発生時のファイル行番号を取得する。
        /// @return 例外発生時のファイル行番号。不明ならば -1 。
        int getLine() const;

        /// @brief 例外発生時の関数名を取得する。
        /// @return 例外発生時の関数名。不明ならば空文字列。
        const wchar_t* getFunction() const;

        /// @brief 例外発生時の付随メッセージを取得する。
        /// @return 例外発生時の付随メッセージ。無いならば空文字列。
        const wchar_t* getMessage() const;

        /// @brief 例外発生時のスタックトレース情報を取得する。
        /// @return 例外発生時のスタックトレース情報。不明ならば空のスタックトレース情報。
        ///
        /// - ライブラリをリンクするプロジェクトのリンカオプションで /DEBUG が指定されており、
        ///   かつデバッグ情報を参照可能な状態の場合、
        ///   シンボル名やファイル名を含む完全なスタックトレース情報を取得できる。
        /// - /DEBUG が指定されていない場合やデバッグ情報を参照できない状態の場合、
        ///   スタックアドレスのみ取得できる。
        ///
        /// デバッグ情報は、VC++の既定のリンカオプションではPDBファイルとして出力される。
        /// このPDBファイルが実行可能ファイルと同じ位置にある場合にデバッグ情報を参照可能となる。
        const ::amdaemon::util::StackTrace& getStackTrace() const;

        /// @brief 例外情報を文字列化する。
        /// @param[in] withoutStackTrace スタックトレースの情報を含めないならば true 。
        /// @return 例外情報文字列。
        const wchar_t* toString(bool withoutStackTrace = false) const;

    private:
        class Impl;

        /// pimpl インスタンス。
        std::unique_ptr<Impl> _impl;
    };

    /// @brief 例外を発生させる。
    /// @param[in] ex 例外。
    ///
    /// 例外フック関数が設定されているならばそれを呼び出す。
    /// そうでなければ標準の例外処理を行い、最後にスローする。
    ///
    /// 通常、この関数を直接呼び出すことはなく、
    /// AMDAEMON_RAISE_EXCEPTION マクロまたは AMDAEMON_RAISE_EXCEPTION_MSG マクロを
    /// 用いて例外を発生させる。
    void raiseException(const Exception& ex);

/// @}
} // namespace amdaemon

/// @addtogroup g_exception
/// @{

#if AMDAEMON_ON_MSVC

/// @brief amdaemon::Exception インスタンスを生成する。
/// @param[in] cate 例外カテゴリ列挙 ExceptionCategory の列挙値名。
#define AMDAEMON_MAKE_EXCEPTION(cate) ¥
    (::amdaemon::Exception( ¥
        ::amdaemon::ExceptionCategory::cate, ¥
        __FILEW__, __LINE__, AMDAEMON_STRING_TO_WIDE(__FUNCSIG__), nullptr, ¥
        __FILE__, __FUNCSIG__))

/// @brief amdaemon::Exception インスタンスを付随メッセージ付きで生成する。
/// @param[in] cate 例外カテゴリ列挙 ExceptionCategory の列挙値名。
/// @param[in] msg 付随メッセージ。 const wchar_t* に変換可能でなければならない。
#define AMDAEMON_MAKE_EXCEPTION_MSG(cate, msg) ¥
    (::amdaemon::Exception( ¥
        ::amdaemon::ExceptionCategory::cate, ¥
        __FILEW__, __LINE__, AMDAEMON_STRING_TO_WIDE(__FUNCSIG__), (msg), ¥
        __FILE__, __FUNCSIG__))

#else // AMDAEMON_ON_MSVC
#define AMDAEMON_MAKE_EXCEPTION(cate) ¥
    (::amdaemon::Exception( ¥
        ::amdaemon::ExceptionCategory::cate, ¥
        AMDAEMON_STRING_TO_WIDE(__FILE__), __LINE__, nullptr, nullptr, __FILE__, __func__))
#define AMDAEMON_MAKE_EXCEPTION_MSG(cate, msg) ¥
    (::amdaemon::Exception( ¥
        ::amdaemon::ExceptionCategory::cate, ¥
        AMDAEMON_STRING_TO_WIDE(__FILE__), __LINE__, nullptr, (msg), __FILE__, __func__))
#endif // AMDAEMON_ON_MSVC

/// @brief 例外を発生させる。
/// @param[in] cate 例外カテゴリ列挙 ExceptionCategory の列挙値名。
#define AMDAEMON_RAISE_EXCEPTION(cate) ¥
    (::amdaemon::raiseException(AMDAEMON_MAKE_EXCEPTION(cate)))

/// @brief 付随メッセージ付きの例外を発生させる。
/// @param[in] cate 例外カテゴリ列挙 ExceptionCategory の列挙値名。
/// @param[in] msg 付随メッセージ。 const wchar_t* に変換可能でなければならない。
#define AMDAEMON_RAISE_EXCEPTION_MSG(cate, msg) ¥
    (::amdaemon::raiseException(AMDAEMON_MAKE_EXCEPTION_MSG(cate, (msg))))

/// @brief ロジック(Logic)例外を発生させる。
/// @note 主に引数チェック時に用いられる。
#define AMDAEMON_RAISE_LOGIC_EXCEPTION() AMDAEMON_RAISE_EXCEPTION(Logic)

/// @brief 付随メッセージ付きのロジック(Logic)例外を発生させる。
/// @param[in] msg 付随メッセージ。 const wchar_t* に変換可能でなければならない。
/// @note 主に引数チェック時に用いられる。
#define AMDAEMON_RAISE_LOGIC_EXCEPTION_MSG(msg) AMDAEMON_RAISE_EXCEPTION_MSG(Logic, (msg))

/// @brief オペレーション(Operation)例外を発生させる。
/// @note 関数呼び出し手順を誤っている時などに用いられる。
#define AMDAEMON_RAISE_OPERATION_EXCEPTION() AMDAEMON_RAISE_EXCEPTION(Operation)

/// @brief 付随メッセージ付きのオペレーション(Operation)例外を発生させる。
/// @param[in] msg 付随メッセージ。 const wchar_t* に変換可能でなければならない。
/// @note 関数呼び出し手順を誤っている時などに用いられる。
#define AMDAEMON_RAISE_OPERATION_EXCEPTION_MSG(msg) ¥
    AMDAEMON_RAISE_EXCEPTION_MSG(Operation, (msg))

/// @brief 実行時(Runtime)例外を発生させる。
/// @note 実行時の状況によって問題が発生した時に用いられる。
#define AMDAEMON_RAISE_RUNTIME_EXCEPTION() AMDAEMON_RAISE_EXCEPTION(Runtime)

/// @brief 付随メッセージ付きの実行時(Runtime)例外を発生させる。
/// @param[in] msg 付随メッセージ。 const wchar_t* に変換可能でなければならない。
/// @note 実行時の状況によって問題が発生した時に用いられる。
#define AMDAEMON_RAISE_RUNTIME_EXCEPTION_MSG(msg) AMDAEMON_RAISE_EXCEPTION_MSG(Runtime, (msg))

/// 回復不能(Fatal)例外を発生させる。
#define AMDAEMON_RAISE_FATAL_EXCEPTION() AMDAEMON_RAISE_EXCEPTION(Fatal)

/// @brief 付随メッセージ付きの回復不能(Fatal)例外を発生させる。
/// @param[in] msg 付随メッセージ。 const wchar_t* に変換可能でなければならない。
#define AMDAEMON_RAISE_FATAL_EXCEPTION_MSG(msg) AMDAEMON_RAISE_EXCEPTION_MSG(Fatal, (msg))

/// @}

#endif // AMDAEMON_EXCEPTION_H