Clock.h

[詳解]

/// @file
/// @brief クロックカウント値とその時間差分計算処理を提供するクラス Clock のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_UTIL_CLOCK_H
#define AMDAEMON_UTIL_CLOCK_H

#include "amdaemon/env.h"
#include "amdaemon/util/TimeSpan.h"

#include <functional>
#include <cstdint>

namespace amdaemon
{
namespace util
{
/// @addtogroup g_util
/// @{

    /// クロックカウント値とその時間差分計算処理を提供するクラス。
    class Clock
    {
    public:
        // 前方宣言
        struct FailMessageHolder;

        /// 内部値の表現型。
        typedef std::int64_t value_type;

        /// @brief コンストラクタ。
        ///
        /// Windows環境である場合、高分解能パフォーマンスカウンタが用いられる。
        Clock();

        /// @brief コンストラクタ。
        /// @param[in] forceStdClock 必ず標準関数 std::clock を用いるならば true 。
        ///
        /// Windows環境かつ引数 forceStdClock に false を指定した場合、
        /// 高分解能パフォーマンスカウンタが用いられる。
        explicit Clock(bool forceStdClock);

        // 下記は暗黙の定義を用いる。
        //Clock(Clock&) = default;
        //‾Clock() = default;
        //Clock& operator=(Clock&) = default;

        /// @brief 現在のクロックカウント値を取得する。
        /// @return 現在のクロックカウント値。
        ///
        /// @exception Exception
        /// 取得処理に失敗した場合。通常、失敗することはない。
        value_type get() const;

        /// @brief 現在のクロックカウント値を取得する。
        /// @param[out] result 現在のクロックカウント値の設定先。
        /// @retval true  取得処理に成功した場合。
        /// @retval false 取得処理に失敗した場合。
        ///
        /// 通常、メンバ関数 #get が失敗することはないため、敢えてこの関数を使う必要はない。
        bool tryGet(value_type& result) const;

        /// @brief 1秒あたりのクロックカウント数を取得する。
        /// @return 1秒あたりのクロックカウント数。
        value_type getCountPerSecond() const
        {
            return _countPerSecond;
        }

        /// @brief クロックカウントの現在値と前回値との時間差分を TimeSpan 値と比較する。
        /// @param[in] prevCount クロックカウントの前回値。
        /// @param[in] span 比較対象の TimeSpan 値。
        /// @retval -1 TimeSpan 値の方が大きい場合。
        /// @retval  0 TimeSpan 値と等しい場合。
        /// @retval +1 TimeSpan 値の方が小さい場合。
        ///
        /// @exception Exception
        /// 現在値の取得処理に失敗した場合。通常、失敗することはない。
        ///
        /// 現在値はメンバ関数 #get によって取得される。
        ///
        /// 現在値と前回値との時間差分が
        /// TimeSpan 値として表せない範囲であっても大小比較することができる。
        int compareSpan(value_type prevCount, const TimeSpan& span) const;

        /// @brief クロックカウントの現在値と前回値との時間差分を TimeSpan 値と比較する。
        /// @param[in] currentCount クロックカウントの現在値。
        /// @param[in] prevCount クロックカウントの前回値。
        /// @param[in] span 比較対象の TimeSpan 値。
        /// @retval -1 TimeSpan 値の方が大きい場合。
        /// @retval  0 TimeSpan 値と等しい場合。
        /// @retval +1 TimeSpan 値の方が小さい場合。
        ///
        /// 現在値と前回値との時間差分が
        /// TimeSpan 値として表せない範囲であっても大小比較することができる。
        int compareSpan(
            value_type currentCount,
            value_type prevCount,
            const TimeSpan& span) const;

        /// @brief クロックカウントの現在値と前回値との時間差分値を算出する。
        /// @param[in] prevCount クロックカウントの前回値。
        /// @return 時間差分値。
        ///
        /// @exception Exception
        /// - 現在値の取得処理に失敗した場合。通常、失敗することはない。
        /// - 時間差分値に変換した値が表現可能範囲に収まらない場合。
        ///
        /// 他の TimeSpan 値との比較を行いたいだけの場合、メンバ関数
        /// compareSpan(value_type, const TimeSpan&) const
        /// の利用を推奨する。
        ///
        /// 現在値はメンバ関数 #get によって取得される。
        ///
        /// Windows環境で高分解能パフォーマンスカウンタを用いている場合、
        /// 環境によっては31日強の差分で表現可能な上限値に達する。
        TimeSpan calcSpan(value_type prevCount) const;

        /// @brief クロックカウントの現在値と前回値との時間差分値を算出する。
        /// @param[in] currentCount クロックカウントの現在値。
        /// @param[in] prevCount クロックカウントの前回値。
        /// @return 時間差分値。
        ///
        /// @exception Exception
        /// 時間差分値に変換した値が表現可能範囲に収まらない場合。
        ///
        /// 他の TimeSpan 値との比較を行いたいだけの場合、メンバ関数
        /// compareSpan(value_type, value_type, const TimeSpan&) const
        /// の利用を推奨する。
        ///
        /// Windows環境で高分解能パフォーマンスカウンタを用いている場合、
        /// 環境によっては31日強の差分で表現可能な上限値に達する。
        TimeSpan calcSpan(value_type currentCount, value_type prevCount) const;

        /// @brief クロックカウントの現在値と前回値との時間差分値を算出する。
        /// @param[in] prevCount クロックカウントの前回値。
        /// @param[out] result 時間差分値の設定先。
        /// @retval true  算出に成功した場合。
        /// @retval false 時間差分値に変換した値が表現可能範囲に収まらない場合。
        ///
        /// 他の TimeSpan 値との比較を行いたいだけの場合、メンバ関数
        /// compareSpan(value_type, const TimeSpan&) const
        /// の利用を推奨する。
        ///
        /// 現在値はメンバ関数 #tryGet によって取得される。
        ///
        /// Windows環境で高分解能パフォーマンスカウンタを用いている場合、
        /// 環境によっては31日強の差分で表現可能な上限値に達する。
        bool tryCalcSpan(value_type prevCount, TimeSpan& result) const;

        /// @brief クロックカウントの現在値と前回値との時間差分値を算出する。
        /// @param[in] currentCount クロックカウントの現在値。
        /// @param[in] prevCount クロックカウントの前回値。
        /// @param[out] result 時間差分値の設定先。
        /// @retval true  算出に成功した場合。
        /// @retval false 時間差分値に変換した値が表現可能範囲に収まらない場合。
        ///
        /// 他の TimeSpan 値との比較を行いたいだけの場合、メンバ関数
        /// compareSpan(value_type, value_type, const TimeSpan&) const
        /// の利用を推奨する。
        ///
        /// Windows環境で高分解能パフォーマンスカウンタを用いている場合、
        /// 環境によっては31日強の差分で表現可能な上限値に達する。
        bool tryCalcSpan(
            value_type currentCount,
            value_type prevCount,
            TimeSpan& result) const;

    private:
        /// クロックカウント値取得関数。
        std::function<bool (value_type&, FailMessageHolder*)> _getter;

        value_type _countPerSecond; ///< 1秒あたりのクロックカウント数。
    };

/// @}
} // namespace util
} // namespace amdaemon

#endif // AMDAEMON_UTIL_CLOCK_H