Merge branch 'master' into pico_sdk
This commit is contained in:
@@ -1,26 +1,25 @@
|
||||
/*! \file piconditionvar.h
|
||||
* \ingroup Thread
|
||||
* \~\brief
|
||||
* \~english Conditional variable
|
||||
* \~russian Conditional variable
|
||||
*/
|
||||
//! \~\file piconditionvar.h
|
||||
//! \~\ingroup Thread
|
||||
//! \~\brief
|
||||
//! \~english Condition variable for waiting and notification between threads
|
||||
//! \~russian Переменная условия для ожидания и уведомления между потоками
|
||||
/*
|
||||
PIP - Platform Independent Primitives
|
||||
PIP - Platform Independent Primitives
|
||||
Condition variable for waiting and notification between threads
|
||||
Stephan Fomenko
|
||||
|
||||
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 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.
|
||||
|
||||
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/>.
|
||||
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
|
||||
@@ -31,92 +30,146 @@
|
||||
|
||||
|
||||
#ifndef PIP_NO_THREADS
|
||||
/**
|
||||
* \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.
|
||||
*/
|
||||
//! \~\ingroup Thread
|
||||
//! \~\brief
|
||||
//! \~english Condition variable used together with external %PIMutex.
|
||||
//! \~russian Переменная условия, используемая вместе с внешним %PIMutex.
|
||||
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, if any.
|
||||
//! \~russian Пробуждает один ожидающий поток, если он есть.
|
||||
void notifyOne();
|
||||
|
||||
/**
|
||||
* \brief Unblocks all threads currently waiting for this condition. If no threads are waiting, the function does
|
||||
* nothing.
|
||||
*/
|
||||
//! \~english Wakes all threads currently waiting on this variable.
|
||||
//! \~russian Пробуждает все потоки, ожидающие на этой переменной.
|
||||
void notifyAll();
|
||||
|
||||
/**
|
||||
* \brief see wait(PIMutex &, const std::function<bool()>&)
|
||||
*/
|
||||
//! \~english Waits until notification, temporarily releasing \a lk while blocked.
|
||||
//! \~russian Ожидает уведомления, временно освобождая \a lk на время блокировки.
|
||||
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.
|
||||
*/
|
||||
virtual void wait(PIMutex & lk, const std::function<bool()> & condition);
|
||||
//! \~\brief
|
||||
//! \~english Waits until \a condition becomes true, rechecking it after each wakeup while \a lk is locked.
|
||||
//! \~russian Ожидает, пока \a condition не станет истинным, повторно проверяя его после каждого пробуждения при заблокированном \a lk.
|
||||
//! \~\details
|
||||
//! \~english
|
||||
//! 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.
|
||||
//!
|
||||
//! \~russian
|
||||
//! Выполнение текущего потока (который должен быть заблокирован с помощью \a lk методом PIMutex::lock())
|
||||
//! приостанавливается до получения уведомления.
|
||||
//!
|
||||
//! В момент блокировки потока функция автоматически вызывает lk.unlock() (PIMutex::unlock()),
|
||||
//! позволяя другим заблокированным потокам продолжить выполнение.
|
||||
//!
|
||||
//! После получения уведомления (явного, от другого потока) функция разблокируется и вызывает
|
||||
//! lk.lock() (PIMutex::lock()), возвращая lk в то же состояние, в котором он находился при вызове
|
||||
//! функции. Затем функция завершается (обратите внимание, что эта последняя блокировка мьютекса
|
||||
//! может снова заблокировать поток перед возвратом).
|
||||
//!
|
||||
//! Обычно функция пробуждается при вызове в другом потоке либо notifyOne(), либо notifyAll().
|
||||
//! Однако некоторые реализации могут создавать ложные пробуждения без вызова любой из этих функций.
|
||||
//! Поэтому пользователи этой функции должны убедиться, что условие для возобновления выполнено.
|
||||
//!
|
||||
//! Если указано condition, функция блокируется только если condition возвращает false,
|
||||
//! а уведомления могут разблокировать поток только когда оно станет true (что особенно полезно
|
||||
//! для проверки ложных пробуждений).
|
||||
//!
|
||||
//! \param lk объект блокировки, используемый методом wait для защиты данных
|
||||
//! \param condition вызываемый объект или функция, не принимающая аргументов и возвращающая значение, которое может быть оценено как
|
||||
//! bool. Вызывается повторно, пока не примет значение true
|
||||
//!
|
||||
virtual void wait(PIMutex & lk, std::function<bool ()> condition);
|
||||
|
||||
/**
|
||||
* \brief see waitFor(PIMutex &, int, const std::function<bool()>&)
|
||||
*/
|
||||
|
||||
//! \~english Waits for at most \a timeout and returns \c true if awakened before it expires.
|
||||
//! \~russian Ожидает не дольше \a timeout и возвращает \c true, если пробуждение произошло до его истечения.
|
||||
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
|
||||
*/
|
||||
virtual bool waitFor(PIMutex & lk, PISystemTime timeout, const std::function<bool()> & condition);
|
||||
//! \brief
|
||||
//! \~english Waits until \a condition becomes true or \a timeout expires.
|
||||
//! \~russian Ожидает, пока \a condition не станет истинным или не истечет \a timeout.
|
||||
//! \~\details
|
||||
//! \~english
|
||||
//! 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
|
||||
//!
|
||||
//! \~russian
|
||||
//! Выполнение текущего потока (который должен быть заблокирован с помощью lk методом PIMutex::lock())
|
||||
//! приостанавливается на время timeout, или до получения уведомления (в зависимости от того,
|
||||
//! что произойдет раньше).
|
||||
//!
|
||||
//! В момент блокировки потока функция автоматически вызывает lk.unlock() (PIMutex::unlock()),
|
||||
//! позволяя другим заблокированным потокам продолжить выполнение.
|
||||
//!
|
||||
//! После получения уведомления или истечения таймаута функция разблокируется и вызывает
|
||||
//! lk.lock() (PIMutex::lock()), возвращая lk в то же состояние, в котором он находился при вызове
|
||||
//! функции. Затем функция завершается (обратите внимание, что эта последняя блокировка мьютекса
|
||||
//! может снова заблокировать поток перед возвратом).
|
||||
//!
|
||||
//! Обычно функция пробуждается при вызове в другом потоке либо notifyOne(), либо notifyAll().
|
||||
//! Однако некоторые реализации могут создавать ложные пробуждения без вызова любой из этих функций.
|
||||
//! Поэтому пользователи этой функции должны убедиться, что условие для возобновления выполнено.
|
||||
//!
|
||||
//! Если указано condition, функция блокируется только если condition возвращает false,
|
||||
//! а уведомления могут разблокировать поток только когда оно станет true (что особенно полезно
|
||||
//! для проверки ложных пробуждений).
|
||||
//!
|
||||
//! \param lk объект блокировки, используемый методом wait для защиты данных
|
||||
//! \param timeout время ожидания
|
||||
//! \param condition вызываемый объект или функция, не принимающая аргументов и возвращающая значение, которое может быть оценено как
|
||||
//! bool. Вызывается повторно, пока не примет значение true
|
||||
//! \return false если достигнут таймаут, или true если условие пробуждения истинно
|
||||
//!
|
||||
virtual bool waitFor(PIMutex & lk, PISystemTime timeout, std::function<bool()> condition);
|
||||
|
||||
private:
|
||||
PRIVATE_DECLARATION(PIP_EXPORT)
|
||||
|
||||
Reference in New Issue
Block a user