merged AI doc, some new pages
This commit is contained in:
@@ -1,8 +1,19 @@
|
||||
/*! \file pitimer.h
|
||||
* \ingroup Thread
|
||||
* \~\brief
|
||||
* \~english Timer
|
||||
* \~russian Таймер
|
||||
* \~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
|
||||
@@ -33,54 +44,71 @@
|
||||
|
||||
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 timer
|
||||
//! \~russian Создает таймер
|
||||
//! \~english Constructs a timer without a tick callback.
|
||||
//! \~russian Создает таймер без обратного вызова тика.
|
||||
explicit PITimer();
|
||||
|
||||
//! \~english Constructs timer with method void(int)
|
||||
//! \~russian Создает таймер с функцией void(int)
|
||||
//! \~english Constructs a timer with a callback that receives the delimiter value.
|
||||
//! \~russian Создает таймер с обратным вызовом, принимающим значение делителя.
|
||||
explicit PITimer(std::function<void(int)> func);
|
||||
|
||||
//! \~english Constructs timer with method void()
|
||||
//! \~russian Создает таймер с функцией void()
|
||||
//! \~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 timer loop delay
|
||||
//! \~russian Возвращает задержку цикла таймера
|
||||
//! \~english Returns the configured base interval between main ticks.
|
||||
//! \~russian Возвращает настроенный базовый интервал между основными тиками.
|
||||
PISystemTime interval() const;
|
||||
|
||||
//! \~english Set timer loop delay
|
||||
//! \~russian Установить интервал таймера
|
||||
//! \~english Sets the base interval. If the timer is running, restarts it with the new value.
|
||||
//! \~russian Устанавливает базовый интервал. Если таймер запущен, перезапускает его с новым значением.
|
||||
void setInterval(PISystemTime interval);
|
||||
|
||||
//! \~english Returns if timer is started
|
||||
//! \~russian Возвращает работает ли таймер
|
||||
//! \~english Returns whether the timer thread is currently running.
|
||||
//! \~russian Возвращает, работает ли сейчас поток таймера.
|
||||
bool isRunning() const;
|
||||
|
||||
//! \~english Return if timer is stopping
|
||||
//! \~russian Возвращает останавливается ли таймер
|
||||
//! \~english Returns whether stop has been requested and shutdown is still in progress.
|
||||
//! \~russian Возвращает, был ли запрошен останов и идет ли еще завершение.
|
||||
bool isStopping() const;
|
||||
|
||||
//! \~english Wait for timer stop
|
||||
//! \~russian Ожидает остановки таймера
|
||||
//! \~english Waits until the timer finishes. Returns \b false if the timeout expires first.
|
||||
//! \~russian Ожидает завершения таймера. Возвращает \b false, если таймаут истек раньше.
|
||||
bool waitForFinish(PISystemTime timeout = {});
|
||||
|
||||
//! \~english Start timer with "interval" loop delay
|
||||
//! \~russian Запустить таймер с интервалом "interval"
|
||||
//! \~english Sets the base interval and starts the timer.
|
||||
//! \~russian Устанавливает базовый интервал и запускает таймер.
|
||||
bool start(PISystemTime interval);
|
||||
|
||||
//! \~english Start timer with "interval" loop delay and tick function "func"
|
||||
//! \~russian Запустить таймер с интервалом "interval" и вызываевымым методом "func"
|
||||
//! \~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)); }
|
||||
EVENT_HANDLER0(bool, start);
|
||||
|
||||
@@ -88,50 +116,52 @@ public:
|
||||
|
||||
EVENT_HANDLER0(void, stop);
|
||||
|
||||
//! \~english Stop timer and wait for finish.
|
||||
//! \~russian Останавливает таймер и ожидает завершения.
|
||||
//! \~english Deprecated overload of \a stopAndWait() that accepts milliseconds.
|
||||
//! \~russian Устаревшая перегрузка \a stopAndWait(), принимающая миллисекунды.
|
||||
void stopAndWait(int timeout_ms) { stopAndWait(PISystemTime::fromMilliseconds(timeout_ms)); }
|
||||
|
||||
//! \~english Stop timer and wait for finish.
|
||||
//! \~russian Останавливает таймер и ожидает завершения.
|
||||
//! \~english Requests stop and waits for the worker thread to finish.
|
||||
//! \~russian Запрашивает остановку и ожидает завершения рабочего потока.
|
||||
void stopAndWait(PISystemTime timeout = {});
|
||||
|
||||
//! \~english Set timer tick function
|
||||
//! \~russian Установить вызываемый метод
|
||||
//! \~english Sets a tick callback that ignores the delimiter value.
|
||||
//! \~russian Устанавливает обратный вызов тика, игнорирующий значение делителя.
|
||||
void setSlot(std::function<void()> func) {
|
||||
ret_func = [func](int) { func(); };
|
||||
}
|
||||
|
||||
//! \~english Set timer tick function
|
||||
//! \~russian Установить вызываемый метод
|
||||
//! \~english Sets a tick callback that receives the current delimiter value.
|
||||
//! \~russian Устанавливает обратный вызов тика, принимающий текущее значение делителя.
|
||||
void setSlot(std::function<void(int)> func) { ret_func = func; }
|
||||
|
||||
//! \~english Enables locking of the internal mutex around tick processing.
|
||||
//! \~russian Включает блокировку внутреннего мьютекса вокруг обработки тиков.
|
||||
void needLockRun(bool need) { lockRun = need; }
|
||||
EVENT_HANDLER0(void, lock) { mutex_.lock(); }
|
||||
EVENT_HANDLER0(void, unlock) { mutex_.unlock(); }
|
||||
|
||||
//! \~english Returns if timer should exec \a maybeCallQueuedEvents() at every tick. By default \b true
|
||||
//! \~russian Возвращает должен ли таймер вызывать \a maybeCallQueuedEvents() каждый тик. По умолчанию \b true
|
||||
//! \~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 Set timer exec \a maybeCallQueuedEvents() at every tick
|
||||
//! \~russian Установает должен ли таймер вызывать \a maybeCallQueuedEvents() каждый тик
|
||||
//! \~english Enables or disables queued-delivery draining through \a maybeCallQueuedEvents() on each main tick.
|
||||
//! \~russian Включает или отключает обработку отложенной доставки через \a maybeCallQueuedEvents() на каждом основном тике.
|
||||
void setCallQueuedEvents(bool yes) { callEvents = yes; }
|
||||
|
||||
//! \~english Add frequency delimiter "delim" with optional delimiter slot "slot"
|
||||
//! \~russian Добавляет делитель частоты "delim" с необязательным методом "slot"
|
||||
//! \~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 Add frequency delimiter "delim" with optional delimiter slot "slot"
|
||||
//! \~russian Добавляет делитель частоты "delim" с необязательным методом "slot"
|
||||
//! \~english Adds a delimiter with a callback that ignores the delimiter value.
|
||||
//! \~russian Добавляет делитель с обратным вызовом, игнорирующим значение делителя.
|
||||
void addDelimiter(int delim, std::function<void()> func);
|
||||
|
||||
//! \~english Add frequency delimiter "delim" with optional delimiter slot "slot"
|
||||
//! \~russian Добавляет делитель частоты "delim" с необязательным методом "slot"
|
||||
//! \~english Adds a delimiter with a pointer-based callback signature.
|
||||
//! \~russian Добавляет делитель с сигнатурой обратного вызова, принимающей указатель.
|
||||
void addDelimiter(int delim, std::function<void(void *)> slot);
|
||||
|
||||
//! \~english Remove all frequency delimiters "delim"
|
||||
//! \~russian Удаляет все делители частоты "delim"
|
||||
//! \~english Removes all delimiters with value \a delim.
|
||||
//! \~russian Удаляет все делители со значением \a delim.
|
||||
void removeDelimiter(int delim);
|
||||
|
||||
EVENT_HANDLER0(void, clearDelimiters) { delims.clear(); }
|
||||
@@ -143,37 +173,47 @@ public:
|
||||
|
||||
//! \fn bool start()
|
||||
//! \brief
|
||||
//! \~english Start timer with \a interval() loop delay
|
||||
//! \~russian Запустить таймер с интервалом \a interval()
|
||||
//! \~english Starts the timer with the current \a interval().
|
||||
//! \~russian Запускает таймер с текущим значением \a interval().
|
||||
|
||||
//! \fn bool restart()
|
||||
//! \brief
|
||||
//! \~english Stop and start timer with \a interval() loop delay
|
||||
//! \~russian Остановить и запустить таймер с интервалом \a interval()
|
||||
//! \~english Stops the timer, then starts it again with the current \a interval().
|
||||
//! \~russian Останавливает таймер, затем снова запускает его с текущим значением \a interval().
|
||||
|
||||
//! \fn bool stop()
|
||||
//! \brief
|
||||
//! \~english Stop timer (don`t wait for finish)
|
||||
//! \~russian Остановить таймер (не дожидается остановки)
|
||||
//! \~english Requests stop and wakes the timer thread, but does not wait for completion.
|
||||
//! \~russian Запрашивает остановку и пробуждает поток таймера, но не ожидает завершения.
|
||||
|
||||
//! \fn void clearDelimiters()
|
||||
//! \brief
|
||||
//! \~english Remove all frequency delimiters
|
||||
//! \~russian Удаляет все делители частоты
|
||||
|
||||
//! \fn void lock()
|
||||
//! \brief
|
||||
//! \~english Locks the internal timer mutex.
|
||||
//! \~russian Блокирует внутренний мьютекс таймера.
|
||||
|
||||
//! \fn void unlock()
|
||||
//! \brief
|
||||
//! \~english Unlocks the internal timer mutex.
|
||||
//! \~russian Разблокирует внутренний мьютекс таймера.
|
||||
|
||||
//! \}
|
||||
//! \events
|
||||
//! \{
|
||||
|
||||
//! \fn void tickEvent(int delimiter)
|
||||
//! \brief
|
||||
//! \~english Raise on timer tick
|
||||
//! \~russian Вызывается каждый тик таймера
|
||||
//! \~english Raised on each timer tick and on configured delimiter ticks.
|
||||
//! \~russian Вызывается на каждом тике таймера и на настроенных тиках делителей.
|
||||
//! \~\details
|
||||
//! \~english
|
||||
//! "delimiter" is frequency delimiter, 1 for main loop.
|
||||
//! "delimiter" is the frequency delimiter, 1 for the main loop.
|
||||
//! \~russian
|
||||
//! "delimiter" - делитель частоты, 1 для основного цикла
|
||||
//! "delimiter" - делитель частоты, 1 для основного цикла.
|
||||
|
||||
|
||||
//! \}
|
||||
@@ -196,7 +236,8 @@ protected:
|
||||
void adjustTimes();
|
||||
void execTick();
|
||||
|
||||
//! Timer execution function, similar to "slot" or event \a timeout(). By default does nothing
|
||||
//! \~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;
|
||||
|
||||
Reference in New Issue
Block a user