147 lines
6.6 KiB
C++
147 lines
6.6 KiB
C++
//! \file piconditionvar.h
|
||
//! \ingroup Thread
|
||
//! \brief
|
||
//! \~english Conditional variable
|
||
//! \~russian Условная переменная
|
||
//!
|
||
//! \details
|
||
//! \~english Object able to block the calling thread until notified to resume.
|
||
//! \~russian Объект, способный заблокировать вызывающий поток до уведомления о продолжении.
|
||
/*
|
||
PIP - Platform Independent Primitives
|
||
|
||
Stephan Fomenko
|
||
|
||
This program is free software: you can redistribute it and/or modify
|
||
it under the terms of the GNU Lesser General Public License as published by
|
||
the Free Software Foundation, either version 3 of the License, or
|
||
(at your option) any later version.
|
||
|
||
This program is distributed in the hope that it will be useful,
|
||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||
GNU Lesser General Public License for more details.
|
||
|
||
You should have received a copy of the GNU Lesser General Public License
|
||
along with this program. If not, see <http://www.gnu.org/licenses/>.
|
||
*/
|
||
|
||
#ifndef PICONDITIONVAR_H
|
||
#define PICONDITIONVAR_H
|
||
|
||
#include "pimutex.h"
|
||
#include "pisystemtime.h"
|
||
|
||
|
||
/**
|
||
* \brief A condition variable is an object able to block the calling thread until notified to resume.
|
||
*
|
||
* It uses a PIMutex to lock the thread when one of its wait functions is called. The thread remains
|
||
* blocked until woken up by another thread that calls a notification function on the same PIConditionVariable object.
|
||
*/
|
||
//! \~english Condition variable for thread synchronization
|
||
//! \~russian Условная переменная для синхронизации потоков
|
||
class PIP_EXPORT PIConditionVariable {
|
||
public:
|
||
NO_COPY_CLASS(PIConditionVariable);
|
||
//! \~english Constructs condition variable
|
||
//! \~russian Создает условную переменную
|
||
explicit PIConditionVariable();
|
||
//! \~english Destroys condition variable
|
||
//! \~russian Уничтожает условную переменную
|
||
virtual ~PIConditionVariable();
|
||
|
||
/**
|
||
* \brief Unblocks one of the threads currently waiting for this condition. If no threads are waiting, the function
|
||
* does nothing. If more than one, it is unspecified which of the threads is selected.
|
||
*/
|
||
//! \~english Wakes one waiting thread
|
||
//! \~russian Будит один ожидающий поток
|
||
void notifyOne();
|
||
|
||
/**
|
||
* \brief Unblocks all threads currently waiting for this condition. If no threads are waiting, the function does
|
||
* nothing.
|
||
*/
|
||
//! \~english Wakes all waiting threads
|
||
//! \~russian Будит все ожидающие потоки
|
||
void notifyAll();
|
||
|
||
/**
|
||
* \brief see wait(PIMutex &, const std::function<bool()>&)
|
||
*/
|
||
//! \~english Wait until notified
|
||
//! \~russian Ожидает уведомления
|
||
virtual void wait(PIMutex & lk);
|
||
|
||
/**
|
||
* \brief Wait until notified
|
||
*
|
||
* The execution of the current thread (which shall have locked with lk method PIMutex::lock()) is blocked
|
||
* until notified.
|
||
*
|
||
* At the moment of blocking the thread, the function automatically calls lk.unlock() (PIMutex::unlock()),
|
||
* allowing other locked threads to continue.
|
||
*
|
||
* Once notified (explicitly, by some other thread), the function unblocks and calls lk.lock() (PIMutex::lock()),
|
||
* leaving lk in the same state as when the function was called. Then the function returns (notice that this last mutex
|
||
* locking may block again the thread before returning).
|
||
*
|
||
* Generally, the function is notified to wake up by a call in another thread either to member notifyOne() or to
|
||
* member notifyAll(). But certain implementations may produce spurious wake-up calls without any of these functions
|
||
* being called. Therefore, users of this function shall ensure their condition for resumption is met.
|
||
*
|
||
* If condition is specified, the function only blocks if condition returns false, and notifications can only unblock
|
||
* the thread when it becomes true (which is specially useful to check against spurious wake-up calls).
|
||
*
|
||
* @param lk lock object used by method wait for data protection
|
||
* @param condition A callable object or function that takes no arguments and returns a value that can be evaluated
|
||
* as a bool. This is called repeatedly until it evaluates to true.
|
||
*/
|
||
//! \~english Wait until notified with condition predicate
|
||
//! \~russian Ожидает уведомления с условием
|
||
virtual void wait(PIMutex & lk, const std::function<bool()> & condition);
|
||
|
||
/**
|
||
* \brief see waitFor(PIMutex &, int, const std::function<bool()>&)
|
||
*/
|
||
//! \~english Wait for timeout
|
||
//! \~russian Ожидает таймаут
|
||
virtual bool waitFor(PIMutex & lk, PISystemTime timeout);
|
||
|
||
/**
|
||
* \brief Wait for timeout or until notified
|
||
*
|
||
* The execution of the current thread (which shall have locked with lk method PIMutex::lock()) is blocked
|
||
* during timeout, or until notified (if the latter happens first).
|
||
*
|
||
* At the moment of blocking the thread, the function automatically calls lk.lock() (PIMutex::lock()), allowing
|
||
* other locked threads to continue.
|
||
*
|
||
* Once notified or once timeout has passed, the function unblocks and calls lk.unlock() (PIMutex::unlock()),
|
||
* leaving lk in the same state as when the function was called. Then the function returns (notice that this last
|
||
* mutex locking may block again the thread before returning).
|
||
*
|
||
* Generally, the function is notified to wake up by a call in another thread either to member notifyOne() or to
|
||
* member notifyAll(). But certain implementations may produce spurious wake-up calls without any of these functions
|
||
* being called. Therefore, users of this function shall ensure their condition for resumption is met.
|
||
*
|
||
* If condition is specified, the function only blocks if condition returns false, and notifications can only unblock
|
||
* the thread when it becomes true (which is especially useful to check against spurious wake-up calls).
|
||
*
|
||
* @param lk lock object used by method wait for data protection
|
||
* @param condition A callable object or function that takes no arguments and returns a value that can be evaluated
|
||
* as a bool. This is called repeatedly until it evaluates to true.
|
||
* @return false if timeout reached or true if wakeup condition is true
|
||
*/
|
||
//! \~english Wait for timeout or until notified with condition predicate
|
||
//! \~russian Ожидает таймаут или уведомление с условием
|
||
virtual bool waitFor(PIMutex & lk, PISystemTime timeout, const std::function<bool()> & condition);
|
||
|
||
private:
|
||
PRIVATE_DECLARATION(PIP_EXPORT)
|
||
};
|
||
|
||
|
||
#endif // PICONDITIONVAR_H
|