.. index:: pair: class; EE::System::Condition .. _doxid-class_e_e_1_1_system_1_1_condition: class EE::System::Condition =========================== .. toctree:: :hidden: enum_EE_System_Condition_LockType.rst Overview ~~~~~~~~ Blocks concurrent access to shared resources from multiple threads. :ref:`More...` .. ref-code-block:: cpp :class: doxyrest-overview-code-block #include class Condition: private :ref:`EE::NonCopyable` { public: // enums enum :ref:`LockType`; // construction :ref:`Condition`(int value = 0); :ref:`~Condition`(); // methods void :target:`lock`(); bool :ref:`waitAndLock`(int awaitedValue, int autoUnlock = false); void :ref:`unlock`(int value); void :target:`unlock`(); int :ref:`operator=`(int value); int :ref:`value`() const; void :ref:`signal`(); void :ref:`invalidate`(); void :ref:`restore`(); }; .. _details-class_e_e_1_1_system_1_1_condition: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ Blocks concurrent access to shared resources from multiple threads. Construction ------------ .. index:: pair: function; Condition .. _doxid-class_e_e_1_1_system_1_1_condition_1acfc73dca41c6495cc171e0e7c37adbd4: .. ref-code-block:: cpp :class: doxyrest-title-code-block Condition(int value = 0) Initializes a :ref:`Condition ` object and sets its internal value to value. Thus using waitAndLock(value, ...) will immediately return. .. _doxid-class_e_e_1_1_system_1_1_condition_1ae5fbbc3bea5419dc950b5115637d9ef2: .. ref-code-block:: cpp :class: doxyrest-title-code-block ~Condition() Default destructor The :ref:`Condition ` is invalidated before destruction Methods ------- .. index:: pair: function; waitAndLock .. _doxid-class_e_e_1_1_system_1_1_condition_1a20b201b9928fd74c0b47a3a20ea8a4e6: .. ref-code-block:: cpp :class: doxyrest-title-code-block bool waitAndLock(int awaitedValue, int autoUnlock = false) Waits until the :ref:`Condition ` 's value == awaitedValue and protects the :ref:`Condition `. You're responsible for unlocking the :ref:`Condition ` with Unlock() after WaitAndLock() returned and after you're done working on protected data, or enabling the auto unlocking mechanism. The :ref:`Condition ` locking guarantees that the condition remains true until you unlock it and that you are the only one that acquired the :ref:`Condition `. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - awaitedValue - the value that should unlock the :ref:`Condition ` * - autoUnlock - :ref:`Condition::AutoUnlock ` (true) to automatically unlock the :ref:`Condition ` protection after it has been validated, or ManualUnlock (false) to manually choose when the :ref:`Condition ` should be unlocked. While a :ref:`Condition ` is locked, both WaitAndLock() and :ref:`operator=() ` will block until the :ref:`Condition ` is unlocked or invalidated. When a :ref:`Condition ` is *automatically* unlocked, its value is not updated. .. rubric:: Returns: true if the awaitedValue has been reached, false otherwise. WaitAndLock() may return even if awaitedValue has not been reached if the :ref:`Condition ` has been disabled through Invalidate(). An invalidated :ref:`Condition ` always returns in an unlocked state. .. index:: pair: function; unlock .. _doxid-class_e_e_1_1_system_1_1_condition_1a03e3e6b4a2c2cf3d7533d14a01fc91aa: .. ref-code-block:: cpp :class: doxyrest-title-code-block void unlock(int value) Unlocks a previously locked :ref:`Condition ` with value as internal value. When the condition is unlocked, it is assumed to have the given value. The condition is thereafter signaled. Unlocking a non-locked :ref:`Condition ` is undefined. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - value - the value the :ref:`Condition ` should have when it is unlocked .. index:: pair: function; operator= .. _doxid-class_e_e_1_1_system_1_1_condition_1aedf1ad07227c1e8cec14e4d61c193776: .. ref-code-block:: cpp :class: doxyrest-title-code-block int operator=(int value) Performs an assignement followed by a :ref:`signal() ` call. The internal :ref:`Condition ` value is updated to :ref:`value() ` and the :ref:`Condition ` is signaled. Note that the :ref:`Condition ` must be unlocked in order to be updated, otherwise it'll block until the :ref:`Condition ` is unlocked. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - value - the value to be assigned to the :ref:`Condition ` .. rubric:: Returns: value .. index:: pair: function; value .. _doxid-class_e_e_1_1_system_1_1_condition_1ace9933f07e328eb4414ef54d7ce030a8: .. ref-code-block:: cpp :class: doxyrest-title-code-block int value() const Get the current internal :ref:`Condition ` value. This is a non-blocking call. .. rubric:: Returns: : the current internal state .. index:: pair: function; signal .. _doxid-class_e_e_1_1_system_1_1_condition_1a192756dd830c9fb9e1e3edeee4723593: .. ref-code-block:: cpp :class: doxyrest-title-code-block void signal() Signals that the :ref:`Condition ` state has changed and that threads waiting on this :ref:`Condition ` should check the new internal value. .. index:: pair: function; invalidate .. _doxid-class_e_e_1_1_system_1_1_condition_1a3008c302ddf7c9cfc62873764fef4ced: .. ref-code-block:: cpp :class: doxyrest-title-code-block void invalidate() Signals the :ref:`Condition ` and disables blocking calls, thus :ref:`waitAndLock() ` does no more wait whatever the awaitedValue is and waiting calls are unlocked, returning false. .. index:: pair: function; restore .. _doxid-class_e_e_1_1_system_1_1_condition_1a44499369008ec11b00af1ad6e4d231c4: .. ref-code-block:: cpp :class: doxyrest-title-code-block void restore() Restores the blocking capabilities of the :ref:`Condition `, possibly previously disabled with :ref:`invalidate() `