Mutex.h

[詳解]

/// @file
/// @brief プロセス間およびスレッド間で排他制御を行うためのクラス Mutex のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_UTIL_MUTEX_H
#define AMDAEMON_UTIL_MUTEX_H

#include "amdaemon/env.h"

#include <memory>

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

    /// @brief プロセス間およびスレッド間で排他制御を行うためのクラス。
    ///
    /// 再帰的なロック取得を許可しており、同一プロセスかつ同一スレッドであればメンバ関数
    /// #lock および #try_lock によるロック取得をブロックなしで何度でも行うことができる。
    /// ただし、ロック取得した回数と同じ回数だけメンバ関数 #unlock を呼び出す必要がある。
    ///
    /// ロック関係のメンバ関数名はC++11のミューテクスインタフェースに準拠する。
    /// これにより std::lock_guard<Mutex>, std::unique_lock<Mutex> 等の利用が可能となる。
    /// 細かな制御を行う場合を除き、それらロック管理クラスの利用が推奨される。
    ///
    /// @code
    /// #include "amdaemon/util/Mutex.h"
    /// #include <mutex>
    /// 
    /// static amdaemon::util::Mutex mutex(L"sample");
    /// 
    /// void funcChild();
    /// 
    /// void funcParent()
    /// {
    ///     // std::lock_guard, std::unique_lock の利用を推奨。
    ///     // 定義時にロック取得され、スコープを抜ける際にロック開放される。
    ///     std::lock_guard<amdaemon::util::Mutex> lock(mutex);
    /// 
    ///     // ロックを行う別の関数を呼び出してみる
    ///     funcChild();
    /// }
    /// 
    /// void funcChild()
    /// {
    ///     // 同一プロセスかつ同一スレッドならば再帰的なロックが可能。
    ///     std::lock_guard<amdaemon::util::Mutex> lock(mutex);
    /// 
    ///     // do something...
    /// }
    /// @endcode
    ///
    /// 多重起動防止には std::unique_lock<Mutex> と std::try_to_lock を用いるとよい。
    ///
    /// @code
    /// #include "amdaemon/util/Mutex.h"
    /// #include <mutex>
    /// 
    /// int main(int, char**)
    /// {
    ///     using amdaemon::util::Mutex;
    /// 
    ///     Mutex multiBootMutex("my_app");
    ///     std::unique_lock<Mutex> multiBootLock(multiBootMutex, std::try_to_lock);
    /// 
    ///     if (!multiBootLock)
    ///     {
    ///         // 多重起動した時の処理
    ///     }
    ///     else
    ///     {
    ///         // 通常時の処理
    ///     }
    /// 
    ///     return 0;
    /// }
    /// @endcode
    class Mutex
    {
    public:
        /// @brief コンストラクタ。
        /// @param[in] name ミューテクス名。 nullptr ならば名前無し。
        explicit Mutex(const wchar_t* name = nullptr);

        /// @brief ムーブコンストラクタ。
        /// @param[in] src ムーブ元。ムーブ後は無効値となる。
        ///
        /// 引数 src がロックを取得中であっても構わずムーブする。
        /// その場合、ロックの開放はムーブ先のインスタンスに対して行う必要がある。
        Mutex(Mutex&& src);

        /// @brief デストラクタ。
        ///
        /// ロックが開放されていない場合、開放処理が行われる。
        /// 再帰的にロックを取得していた場合でもすべて開放されるが、
        /// このインスタンスでロックを取得した回数を超えて開放処理が行われることはない。
        ‾Mutex();

        /// @brief ムーブ代入演算子。
        /// @param[in] r ムーブ元となる右辺値。ムーブ後は無効値となる。
        /// @return 自身の参照。
        ///
        /// 引数 r がロックを取得中であっても構わずムーブする。
        /// その場合、ロックの開放はムーブ先のインスタンスに対して行う必要がある。
        Mutex& operator=(Mutex&& r);

        /// @brief ミューテクスが有効値であるか否かを取得する。
        /// @retval true  有効値である場合。
        /// @retval false 無効値である場合。
        ///
        /// コンストラクタでの初期化に失敗した場合や、ムーブ済みの場合に false を返す。
        /// 無効値である場合、ロック関係のメンバ関数は何も行わずに失敗する。
        bool valid() const;

        /// @brief ロックを取得する。取得できるまでブロックする。
        /// @retval true  ロックを取得できた場合。
        /// @retval false 無効値である等の理由でロックを取得できなかった場合。
        bool lock();

        /// @brief ロックの取得を試行する。取得できなければ即座に false を返す。
        /// @retval true  ロックを取得できた場合。
        /// @retval false 既にロック取得されている等の理由でロックを取得できなかった場合。
        bool try_lock();

        /// @brief ロックを開放する。
        /// @retval true  ロックを開放できた場合。
        /// @retval false 既に開放済み等の理由でロックを開放できなかった場合。
        bool unlock();

    private:
        class Impl;

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

    private:
        // コピー禁止
        Mutex(const Mutex&);            // 宣言のみ
        Mutex& operator=(const Mutex&); // 宣言のみ
    };

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

#endif // AMDAEMON_UTIL_MUTEX_H