/*---------------------------------------------------------------------------* Project: Horizon File: os_LightSemaphore.h Copyright (C)2009 Nintendo Co., Ltd. All rights reserved. These coded instructions, statements, and computer programs contain proprietary information of Nintendo of America Inc. and/or Nintendo Company Ltd., and are protected by Federal copyright law. They may not be disclosed to third parties or copied or duplicated in any form, in whole or in part, without the prior written consent of Nintendo. $Rev: 28867 $ *---------------------------------------------------------------------------*/ #ifndef NN_OS_OS_LIGHTSEMAPHORE_H_ #define NN_OS_OS_LIGHTSEMAPHORE_H_ #ifdef __cplusplus #include #include #include #include namespace nn { namespace os { /*! @file @brief LightSemaphore に関するAPI の宣言 :include nn/os.h */ /*!--------------------------------------------------------------------------* @brief スレッド間でリソース数の排他制御を行う同期機構です。 内部にカウンタ値を持ち、これを各スレッドで減算/加算する形で リソース数を管理します。 カウンタ値が 0 の場合は 1 以上になるまで待つことができます。 複数の同期オブジェクトを同時に待つことができないという点を除いて nn::os::LightSemaphore の方が nn::os::Semaphore より 優れているため、通常は nn::os::LightSemaphore を使用すべきです。 このクラスの初期化/終了以外のメンバ関数はスレッドセーフです。 *---------------------------------------------------------------------------*/ class LightSemaphore { private: struct DecrementIfPositive { bool operator()(s32& x) { if( x > 0 ) { --x; return true; } else { return false; } } }; struct LimitedAdd { s32 max; s32 value; s32 beforeUpdate; bool operator()(s32& x) { beforeUpdate = x; if( x > max - value ) { x = max; } else { x += value; } return true; } }; private: WaitableCounter m_Counter; s32 m_Max; public: //---------------------------------------- //! @name 初期化/終了 //@{ /*!--------------------------------------------------------------------------* @brief コンストラクタです。 初期化を行わないコンストラクタです。 別途 @ref Initialize を呼び出す必要があります。 *---------------------------------------------------------------------------*/ LightSemaphore() {} /*!--------------------------------------------------------------------------* @brief コンストラクタです。 初期化を行うコンストラクタです。 別途 @ref Initialize を呼び出す必要はありません。 @param[in] initialCount 初期カウンタ値を指定します。 @param[in] maxCount カウンタ値の最大値を指定します。 *---------------------------------------------------------------------------*/ LightSemaphore(s32 initialCount, s32 maxCount) { Initialize(initialCount, maxCount); } /*!--------------------------------------------------------------------------* @brief 初期化を行います。 @param[in] initialCount 初期カウンタ値を指定します。 @param[in] maxCount カウンタ値の最大値を指定します。 @return なし。 *---------------------------------------------------------------------------*/ void Initialize(s32 initialCount, s32 maxCount) { NN_MIN_TASSERT_( initialCount, 0 ); NN_MIN_TASSERT_( maxCount, 1 ); NN_MAX_TASSERT_( initialCount, maxCount ); *m_Counter = initialCount; m_Max = maxCount; } /*!--------------------------------------------------------------------------* @brief 終了処理を行います。 @return なし。 *---------------------------------------------------------------------------*/ void Finalize() {} //@} //---------------------------------------- //! @name デバッグ用情報取得 //@{ /*!--------------------------------------------------------------------------* @brief コンストラクタまたは @ref Initialize で指定したカウンタ値の 最大値を取得します。 @return 設定されているカウンタ値の最大値を返します。 *---------------------------------------------------------------------------*/ s32 GetMax() const { return m_Max; } /*!--------------------------------------------------------------------------* @brief 現在のカウンタ値を取得します。 @return 現在のカウンタ値を返します。 *---------------------------------------------------------------------------*/ s32 GetCount() const { return *m_Counter; } //@} //---------------------------------------- //! @name カウンタの操作と待ち合わせ //@{ /*!--------------------------------------------------------------------------* @brief カウンタ値を 1 減算します。 カウンタ値が 0 であった場合は 1 以上になるまで待ったうえで 減算を行います。 @return なし。 *---------------------------------------------------------------------------*/ void Acquire() { while( ! TryAcquire() ) { m_Counter.WaitIfLessThan(1); } } /*!--------------------------------------------------------------------------* @brief カウンタ値を 1 減算しようとします。 カウンタ値が 0 であった場合は減算を行わずに返ります。 @return 減算を行ったなら true、カウンタ値が 0 であったために 減算を行えなかった場合は false を返します。 *---------------------------------------------------------------------------*/ bool TryAcquire() { DecrementIfPositive updater; return m_Counter->AtomicUpdateConditional(updater); } /*!--------------------------------------------------------------------------* @brief カウンタ値に加算します。 カウンタ値が 0 であり、かついずれかのスレッドが カウンタ値が 1 以上になるのを待機している場合 カウンタ値が加算されるとそのスレッドの待機が解除されます。 複数のスレッドが待機している場合に 2 以上の値を 加算すると複数のスレッドの待機が解除されます。 加算した値より待機しているスレッドの方が多い場合は 加算した値分のスレッドだけが起床し、 残りは待機したままです。 起床するスレッドはスレッドの優先度に応じて優先度が高い方から起床します。 @param[in] releaseCount 加算する値を指定します。 1 以上でなければなりません。 指定しなかった場合は 1 加算します。 @return 加算前のカウンタ値を返します。 *---------------------------------------------------------------------------*/ s32 Release(s32 releaseCount = 1); //@} class ScopedAcquire { private: LightSemaphore* m_Semaphore; public: ScopedAcquire(LightSemaphore& semaphore, bool wait = true) : m_Semaphore(wait ? (semaphore.Acquire(), &semaphore) : (semaphore.TryAcquire() ? &semaphore : 0)) {} bool Aquired() const { return m_Semaphore != 0; } void Detach() { this->m_Semaphore = 0; } ~ScopedAcquire() { if (m_Semaphore) { m_Semaphore->Release(); } } }; }; }} // namespace nn::os #endif // __cplusplus // 以下、C 用宣言 #include /*! @addtogroup nn_os @{ @defgroup nn_os_LightSemaphore_c LightSemaphore (C) @brief @ref nn::os::LightSemaphore の C インタフェースモジュールです。 @{ */ /*! @struct nnosLightSemaphore @brief ライトセマフォを表す C の構造体です。 @brief 対応するクラス @ref nn::os::LightSemaphore を参照してください。 */ NN_UTIL_DETAIL_CLIBIMPL_DEFINE_BUFFER_CLASS(nnosLightSemaphore, nn::os::LightSemaphore, 8, u32); /*! @brief 対応する C++ 関数 @ref nn::os::LightSemaphore::LightSemaphore を参照してください。 */ NN_EXTERN_C void nnosLightSemaphoreInitialize(nnosLightSemaphore* this_, s32 initialCount, s32 maxCount); /*! @brief 対応する C++ 関数 @ref nn::os::LightSemaphore::GetMax を参照してください。 */ NN_EXTERN_C s32 nnosLightSemaphoreGetMax(nnosLightSemaphore* p); /*! @brief 対応する C++ 関数 @ref nn::os::LightSemaphore::GetCount を参照してください。 */ NN_EXTERN_C s32 nnosLightSemaphoreGetCount(nnosLightSemaphore* p); /*! @brief 対応する C++ 関数 @ref nn::os::LightSemaphore::Release を参照してください。 */ NN_EXTERN_C s32 nnosLightSemaphoreRelease(nnosLightSemaphore* this_, s32 releaseCount); /*! @brief 対応する C++ 関数 @ref nn::os::LightSemaphore::Acquire を参照してください。 */ NN_EXTERN_C void nnosLightSemaphoreAcquire(nnosLightSemaphore* this_); /*! @brief 対応する C++ 関数 @ref nn::os::LightSemaphore::TryAcquire を参照してください。 */ NN_EXTERN_C bool nnosLightSemaphoreTryAcquire(nnosLightSemaphore* this_); /*! @brief 対応する C++ 関数 @ref nn::os::LightSemaphore::Finalize を参照してください。 */ NN_EXTERN_C void nnosLightSemaphoreFinalize(nnosLightSemaphore* this_); /*! @} @} */ #endif // ifndef NN_OS_OS_LIGHTSEMAPHORE_H_