StackTrace.h

[詳解]

/// @file
/// @brief スタックトレース情報クラス StackTrace のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_UTIL_STACKTRACE_H
#define AMDAEMON_UTIL_STACKTRACE_H

#include "amdaemon/env.h"

#include <vector>
#include <memory>

namespace amdaemon
{
namespace util
{
    /// @brief スタックトレース情報クラス。
    /// @ingroup g_util g_exception
    ///
    /// - ライブラリをリンクするプロジェクトのリンカオプションで /DEBUG が指定されており、
    ///   かつデバッグ情報を参照可能な状態の場合、
    ///   シンボル名やファイル名を含む完全なスタックトレース情報を取得できる。
    /// - /DEBUG が指定されていない場合やデバッグ情報を参照できない状態の場合、
    ///   スタックアドレスのみ取得できる。
    ///
    /// デバッグ情報は、VC++の既定のリンカオプションではPDBファイルとして出力される。
    /// このPDBファイルが実行可能ファイルと同じ位置にある場合にデバッグ情報を参照可能となる。
    class StackTrace
    {
    public:
        /// スタックトレースユニットクラス。
        class Unit
        {
        public:
            /// @brief コンストラクタ。
            /// @param[in] address スタックアドレス。
            /// @param[in] module モジュール名。不明ならば nullptr 。
            /// @param[in] symbol シンボル名。不明ならば nullptr 。
            /// @param[in] file ファイル名。不明ならば nullptr 。
            /// @param[in] line ファイル行番号。不明ならば負数。
            Unit(
                const void* address,
                const wchar_t* module,
                const wchar_t* symbol,
                const wchar_t* file,
                int line);

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

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

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

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

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

            /// @brief スタックアドレスを取得する。
            /// @return スタックアドレス。
            const void* getAddress() const;

            /// @brief モジュール名を取得する。
            /// @return モジュール名。不明ならば空文字列。
            const wchar_t* getModule() const;

            /// @brief シンボル名を取得する。
            /// @return シンボル名。不明ならば空文字列。
            /// @note 関数名を表す。
            const wchar_t* getSymbol() const;

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

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

            /// @brief スタックトレースユニットの文字列表現を取得する。
            /// @return スタックトレースユニットの文字列表現。
            const wchar_t* toString() const;

        private:
            class Impl;

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

    public:
        /// @brief この関数を呼び出した時点でのスタックトレース情報を作成する。
        /// @param[in] ignoreThis
        ///     この関数自身をスタックトレース情報に含めないならば true 。
        /// @return スタックトレース情報。
        static StackTrace make(bool ignoreThis = false);

        /// @brief スタックトレース情報作成のための初期化を行う。
        /// @retval true  処理に成功したか、既に初期化済みである場合。
        /// @retval false 処理に失敗した場合。
        ///
        /// この関数を呼ばずとも初回のスタックトレース情報作成時に初期化される。
        /// ただし、初期化処理にはやや時間が掛かり、ヒープもいくらか消費するため、
        /// この関数で予め初期化を行っておくことは有用である。
        static bool initialize();

    public:
        /// @brief コンストラクタ。
        ///
        /// 空のスタックトレース情報で初期化される。
        StackTrace();

    private:
        /// @brief コンストラクタ。
        /// @param[in] スタックトレースユニット配列。
        /// @see make
        StackTrace(std::vector<Unit>&& units);

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

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

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

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

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

        /// @brief スタックトレースユニット配列を取得する。
        /// @return スタックトレースユニット配列。
        const std::vector<Unit>& getUnits() const;

        /// @brief スタックトレースの文字列表現を取得する。
        /// @return スタックトレースの文字列表現。空ならば空文字列。
        const wchar_t* toString() const;

        /// @brief スタックトレース情報が空であるか否かを取得する。
        /// @retval true  空である場合。
        /// @retval false 空ではない場合。
        bool empty() const { return getUnits().empty(); }

    private:
        class Impl;

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

#endif // AMDAEMON_UTIL_STACKTRACE_H