251 lines
12 KiB
C++
251 lines
12 KiB
C++
/*! \file pitimer.h
|
|
* \ingroup Thread
|
|
* \~\brief
|
|
* \~english Timer object backed by an internal thread
|
|
* \~russian Объект таймера, работающий на внутреннем потоке
|
|
*
|
|
* \~\details
|
|
* \~english
|
|
* %PITimer uses an internal %PIThread to generate best-effort periodic ticks.
|
|
* When queued delivery is enabled, the timer also drains events addressed to it
|
|
* as performer through \a maybeCallQueuedEvents() on the main tick.
|
|
* \~russian
|
|
* %PITimer использует внутренний %PIThread для генерации периодических тиков
|
|
* с практической, но не строго гарантированной точностью. Когда включена
|
|
* отложенная доставка, таймер также обрабатывает события, адресованные ему как
|
|
* исполнителю, через \a maybeCallQueuedEvents() на основном тике.
|
|
*/
|
|
/*
|
|
PIP - Platform Independent Primitives
|
|
Timer
|
|
Ivan Pelipenko peri4ko@yandex.ru
|
|
|
|
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 PITIMER_H
|
|
#define PITIMER_H
|
|
|
|
#include "piconditionvar.h"
|
|
#include "piobject.h"
|
|
#include "pisystemtime.h"
|
|
|
|
|
|
class PIThread;
|
|
|
|
//! \~\ingroup Thread
|
|
//! \~\brief
|
|
//! \~english Periodic timer that emits ticks from an internal worker thread.
|
|
//! \~russian Периодический таймер, который выдает тики из внутреннего рабочего потока.
|
|
//! \~\details
|
|
//! \~english
|
|
//! The main tick uses delimiter value 1. Additional frequency delimiters can
|
|
//! request extra callbacks every \a n ticks. This class does not promise exact
|
|
//! wake-up timing or scheduler fairness.
|
|
//! \~russian
|
|
//! Основной тик использует значение делителя 1. Дополнительные делители частоты
|
|
//! позволяют запрашивать дополнительные вызовы каждые \a n тиков. Этот класс не
|
|
//! обещает точное время пробуждения или справедливость планировщика.
|
|
class PIP_EXPORT PITimer: public PIObject {
|
|
PIOBJECT_SUBCLASS(PITimer, PIObject);
|
|
|
|
public:
|
|
NO_COPY_CLASS(PITimer);
|
|
|
|
//! \~english Constructs a timer without a tick callback.
|
|
//! \~russian Создает таймер без обратного вызова тика.
|
|
explicit PITimer();
|
|
|
|
//! \~english Constructs a timer with a callback that receives the delimiter value.
|
|
//! \~russian Создает таймер с обратным вызовом, принимающим значение делителя.
|
|
explicit PITimer(std::function<void(int)> func);
|
|
|
|
//! \~english Constructs a timer with a callback that ignores the delimiter value.
|
|
//! \~russian Создает таймер с обратным вызовом, игнорирующим значение делителя.
|
|
explicit PITimer(std::function<void()> func);
|
|
|
|
//! \~english Destroys the timer and stops its internal worker thread.
|
|
//! \~russian Уничтожает таймер и останавливает его внутренний рабочий поток.
|
|
virtual ~PITimer();
|
|
|
|
//! \~english Returns the configured base interval between main ticks.
|
|
//! \~russian Возвращает настроенный базовый интервал между основными тиками.
|
|
PISystemTime interval() const;
|
|
|
|
//! \~english Sets the base interval. If the timer is running, restarts it with the new value.
|
|
//! \~russian Устанавливает базовый интервал. Если таймер запущен, перезапускает его с новым значением.
|
|
void setInterval(PISystemTime interval);
|
|
|
|
//! \~english Returns whether the timer thread is currently running.
|
|
//! \~russian Возвращает, работает ли сейчас поток таймера.
|
|
bool isRunning() const;
|
|
|
|
//! \~english Returns whether stop has been requested and shutdown is still in progress.
|
|
//! \~russian Возвращает, был ли запрошен останов и идет ли еще завершение.
|
|
bool isStopping() const;
|
|
|
|
//! \~english Waits until the timer finishes. Returns \b false if the timeout expires first.
|
|
//! \~russian Ожидает завершения таймера. Возвращает \b false, если таймаут истек раньше.
|
|
bool waitForFinish(PISystemTime timeout = {});
|
|
|
|
//! \~english Sets the base interval and starts the timer.
|
|
//! \~russian Устанавливает базовый интервал и запускает таймер.
|
|
bool start(PISystemTime interval);
|
|
|
|
//! \~english Sets the base interval and tick callback, then starts the timer.
|
|
//! \~russian Устанавливает базовый интервал и обратный вызов тика, затем запускает таймер.
|
|
bool start(PISystemTime interval, std::function<void()> func);
|
|
|
|
//! \~english Deprecated overload of \a start() that accepts milliseconds.
|
|
//! \~russian Устаревшая перегрузка \a start(), принимающая миллисекунды.
|
|
bool start(double interval_ms) DEPRECATEDM("use start(PISystemTime)") { return start(PISystemTime::fromMilliseconds(interval_ms)); }
|
|
|
|
//! \~english Deprecated overload of \a stopAndWait() that accepts milliseconds.
|
|
//! \~russian Устаревшая перегрузка \a stopAndWait(), принимающая миллисекунды.
|
|
void stopAndWait(int timeout_ms) { stopAndWait(PISystemTime::fromMilliseconds(timeout_ms)); }
|
|
|
|
//! \~english Requests stop and waits for the worker thread to finish.
|
|
//! \~russian Запрашивает остановку и ожидает завершения рабочего потока.
|
|
void stopAndWait(PISystemTime timeout = {});
|
|
|
|
//! \~english Sets a tick callback that ignores the delimiter value.
|
|
//! \~russian Устанавливает обратный вызов тика, игнорирующий значение делителя.
|
|
void setSlot(std::function<void()> func);
|
|
|
|
//! \~english Sets a tick callback that receives the current delimiter value.
|
|
//! \~russian Устанавливает обратный вызов тика, принимающий текущее значение делителя.
|
|
void setSlot(std::function<void(int)> func);
|
|
|
|
//! \~english Enables locking of the internal mutex around tick processing.
|
|
//! \~russian Включает блокировку внутреннего мьютекса вокруг обработки тиков.
|
|
void needLockRun(bool need) { lockRun = need; }
|
|
|
|
//! \~english Returns whether the timer drains queued delivery for itself as performer on each main tick. By default \b true.
|
|
//! \~russian Возвращает, должен ли таймер обрабатывать отложенную доставку для себя как исполнителя на каждом основном тике. По
|
|
//! умолчанию \b true.
|
|
bool isCallQueuedEvents() const { return callEvents; }
|
|
|
|
//! \~english Enables or disables queued-delivery draining through \a maybeCallQueuedEvents() on each main tick.
|
|
//! \~russian Включает или отключает обработку отложенной доставки через \a maybeCallQueuedEvents() на каждом основном тике.
|
|
void setCallQueuedEvents(bool yes) { callEvents = yes; }
|
|
|
|
//! \~english Adds a frequency delimiter that invokes \a func every \a delim main ticks.
|
|
//! \~russian Добавляет делитель частоты, который вызывает \a func каждые \a delim основных тиков.
|
|
void addDelimiter(int delim, std::function<void(int)> func = nullptr);
|
|
|
|
//! \~english Adds a delimiter with a callback that ignores the delimiter value.
|
|
//! \~russian Добавляет делитель с обратным вызовом, игнорирующим значение делителя.
|
|
void addDelimiter(int delim, std::function<void()> func);
|
|
|
|
//! \~english Adds a delimiter with a pointer-based callback signature.
|
|
//! \~russian Добавляет делитель с сигнатурой обратного вызова, принимающей указатель.
|
|
void addDelimiter(int delim, std::function<void(void *)> slot);
|
|
|
|
//! \~english Removes all delimiters with value \a delim.
|
|
//! \~russian Удаляет все делители со значением \a delim.
|
|
void removeDelimiter(int delim);
|
|
|
|
|
|
//! \handlers
|
|
//! \{
|
|
|
|
//! \fn bool start()
|
|
//! \brief
|
|
//! \~english Starts the timer with the current \a interval().
|
|
//! \~russian Запускает таймер с текущим значением \a interval().
|
|
EVENT_HANDLER0(bool, start);
|
|
|
|
//! \fn bool restart()
|
|
//! \brief
|
|
//! \~english Stops the timer, then starts it again with the current \a interval().
|
|
//! \~russian Останавливает таймер, затем снова запускает его с текущим значением \a interval().
|
|
EVENT_HANDLER0(bool, restart);
|
|
|
|
//! \fn bool stop()
|
|
//! \brief
|
|
//! \~english Requests stop and wakes the timer thread, but does not wait for completion.
|
|
//! \~russian Запрашивает остановку и пробуждает поток таймера, но не ожидает завершения.
|
|
EVENT_HANDLER0(void, stop);
|
|
|
|
//! \fn void clearDelimiters()
|
|
//! \brief
|
|
//! \~english Remove all frequency delimiters
|
|
//! \~russian Удаляет все делители частоты
|
|
EVENT_HANDLER0(void, clearDelimiters) { delims.clear(); }
|
|
|
|
//! \fn void lock()
|
|
//! \brief
|
|
//! \~english Locks the internal timer mutex.
|
|
//! \~russian Блокирует внутренний мьютекс таймера.
|
|
EVENT_HANDLER0(void, lock) { mutex_.lock(); }
|
|
|
|
//! \fn void unlock()
|
|
//! \brief
|
|
//! \~english Unlocks the internal timer mutex.
|
|
//! \~russian Разблокирует внутренний мьютекс таймера.
|
|
EVENT_HANDLER0(void, unlock) { mutex_.unlock(); }
|
|
|
|
//! \}
|
|
//! \events
|
|
//! \{
|
|
|
|
//! \fn void tickEvent(int delimiter)
|
|
//! \brief
|
|
//! \~english Raised on each timer tick and on configured delimiter ticks.
|
|
//! \~russian Вызывается на каждом тике таймера и на настроенных тиках делителей.
|
|
//! \~\details
|
|
//! \~english
|
|
//! "delimiter" is the frequency delimiter, 1 for the main loop.
|
|
//! \~russian
|
|
//! "delimiter" - делитель частоты, 1 для основного цикла.
|
|
EVENT1(tickEvent, int, delimiter);
|
|
|
|
//! \}
|
|
|
|
protected:
|
|
struct PIP_EXPORT Delimiter {
|
|
Delimiter(std::function<void(int)> func_ = nullptr, int delim_ = 1) {
|
|
func = std::move(func_);
|
|
delim = delim_;
|
|
}
|
|
std::function<void(int)> func;
|
|
int delim = 0;
|
|
int tick = 0;
|
|
};
|
|
|
|
void initFirst();
|
|
void init() const;
|
|
|
|
void threadFunc();
|
|
void adjustTimes();
|
|
void execTick();
|
|
|
|
//! \~english Virtual tick method. The main loop passes delimiter 1, additional delimiters pass their own value.
|
|
//! \~russian Виртуальный метод тика. Основной цикл передает делитель 1, дополнительные делители передают свое значение.
|
|
virtual void tick(int delimiter) {}
|
|
|
|
PIThread * thread = nullptr;
|
|
std::atomic_bool lockRun = {false}, callEvents = {true};
|
|
PIMutex mutex_;
|
|
PISystemTime m_interval, m_interval_x5;
|
|
PISystemTime m_time_next;
|
|
std::function<void()> ret_func = nullptr;
|
|
std::function<void(int)> ret_func_delim = nullptr;
|
|
PIVector<Delimiter> delims;
|
|
PIConditionVariable event;
|
|
};
|
|
|
|
|
|
#endif // PITIMER_H
|