merged AI doc, some new pages
This commit is contained in:
@@ -1,9 +1,19 @@
|
||||
/*! \file pithread.h
|
||||
* \ingroup Thread
|
||||
* \~\brief
|
||||
* \~english Thread class
|
||||
* \~russian Класс потока
|
||||
*/
|
||||
//! \~\file pithread.h
|
||||
//! \~\ingroup Thread
|
||||
//! \~\brief
|
||||
//! \~english Runtime thread object with optional loop execution
|
||||
//! \~russian Объект потока выполнения с необязательным циклом
|
||||
//!
|
||||
//! \~\details
|
||||
//! \~english
|
||||
//! %PIThread runs \a begin(), \a run() and \a end() on a dedicated system
|
||||
//! thread. In loop mode it also drains queued delivery addressed to the thread
|
||||
//! object as performer through \a maybeCallQueuedEvents() before each iteration.
|
||||
//! \~russian
|
||||
//! %PIThread выполняет \a begin(), \a run() и \a end() в отдельном системном
|
||||
//! потоке. В циклическом режиме он также обрабатывает отложенную доставку,
|
||||
//! адресованную объекту потока как исполнителю, через
|
||||
//! \a maybeCallQueuedEvents() перед каждой итерацией.
|
||||
/*
|
||||
PIP - Platform Independent Primitives
|
||||
Thread
|
||||
@@ -66,9 +76,26 @@ public:
|
||||
static __PIThreadCollection_Initializer__ __PIThreadCollection_initializer__;
|
||||
#endif // MICRO_PIP
|
||||
|
||||
//! \~english Callback executed by %PIThread with the current \a data() pointer.
|
||||
//! \~russian Обратный вызов, который %PIThread выполняет с текущим указателем \a data().
|
||||
typedef std::function<void(void *)> ThreadFunc;
|
||||
|
||||
|
||||
//! \~\ingroup Thread
|
||||
//! \~\brief
|
||||
//! \~english Thread object that executes work on a dedicated system thread.
|
||||
//! \~russian Объект потока, выполняющий работу в отдельном системном потоке.
|
||||
//! \~\details
|
||||
//! \~english
|
||||
//! The default loop calls \a begin(), then repeats queued-delivery draining for
|
||||
//! this performer object plus \a run(), and finally calls \a end() when
|
||||
//! stopping. Use \a startOnce() when only one pass is needed and no repeated
|
||||
//! queued draining loop is required.
|
||||
//! \~russian
|
||||
//! Стандартный цикл вызывает \a begin(), затем повторяет обработку отложенной
|
||||
//! доставки для этого объекта-исполнителя вместе с \a run(), а при остановке
|
||||
//! вызывает \a end(). Используйте \a startOnce(), когда нужен только один
|
||||
//! проход без повторяющегося цикла обработки очереди.
|
||||
class PIP_EXPORT PIThread: public PIObject {
|
||||
PIOBJECT_SUBCLASS(PIThread, PIObject);
|
||||
#ifndef MICRO_PIP
|
||||
@@ -78,22 +105,24 @@ class PIP_EXPORT PIThread: public PIObject {
|
||||
public:
|
||||
NO_COPY_CLASS(PIThread);
|
||||
|
||||
//! \~english Contructs thread with custom data "data", external function "func" and main loop delay "loop_delay"
|
||||
//! \~russian Создает поток с данными "data", функцией "func" и задержкой цикла "loop_delay"
|
||||
//! \~english Constructs a thread with user data, callback and optional immediate start.
|
||||
//! \~russian Создает поток с пользовательскими данными, обратным вызовом и необязательным немедленным запуском.
|
||||
PIThread(void * data, ThreadFunc func, bool startNow = false, PISystemTime loop_delay = {});
|
||||
|
||||
//! \~english Contructs thread with external function "func" and main loop delay "loop_delay"
|
||||
//! \~russian Создает поток с функцией "func" и задержкой цикла "loop_delay"
|
||||
//! \~english Constructs a thread with a callback without custom data.
|
||||
//! \~russian Создает поток с обратным вызовом без пользовательских данных.
|
||||
PIThread(std::function<void()> func, bool startNow = false, PISystemTime loop_delay = {});
|
||||
|
||||
//! \~english Contructs thread with main loop delay "loop_delay"
|
||||
//! \~russian Создает поток с задержкой цикла "loop_delay"
|
||||
//! \~english Constructs a subclass-oriented thread with an optional loop delay.
|
||||
//! \~russian Создает поток для наследования с необязательной задержкой цикла.
|
||||
PIThread(bool startNow = false, PISystemTime loop_delay = {});
|
||||
|
||||
//! \~english Destroys the thread object. If it is still running, destruction forces termination.
|
||||
//! \~russian Уничтожает объект потока. Если поток еще работает, при уничтожении выполняется принудительное завершение.
|
||||
virtual ~PIThread();
|
||||
|
||||
//! \~english Priority of thread
|
||||
//! \~russian Приоритет потока
|
||||
//! \~english Thread priority hint.
|
||||
//! \~russian Подсказка приоритета потока.
|
||||
enum Priority {
|
||||
piLowerst /** \~english Lowest \~russian Низший */,
|
||||
piLow /** \~english Low \~russian Низкий */,
|
||||
@@ -105,128 +134,126 @@ public:
|
||||
};
|
||||
|
||||
|
||||
//! \~english Start thread
|
||||
//! \~russian Запускает поток
|
||||
//! \~english Starts the thread with the stored callback and loop delay.
|
||||
//! \~russian Запускает поток с сохраненными обратным вызовом и задержкой цикла.
|
||||
bool start();
|
||||
|
||||
//! \~english Start thread
|
||||
//! \~russian Запускает поток
|
||||
//! \~english Stores a new loop delay and starts the thread.
|
||||
//! \~russian Сохраняет новую задержку цикла и запускает поток.
|
||||
bool start(PISystemTime loop_delay);
|
||||
|
||||
//! \~english Start thread
|
||||
//! \~russian Запускает поток
|
||||
//! \~english Stores a callback and starts the thread.
|
||||
//! \~russian Сохраняет обратный вызов и запускает поток.
|
||||
bool start(ThreadFunc func);
|
||||
|
||||
//! \~english Start thread
|
||||
//! \~russian Запускает поток
|
||||
//! \~english Stores a callback and loop delay, then starts the thread.
|
||||
//! \~russian Сохраняет обратный вызов и задержку цикла, затем запускает поток.
|
||||
bool start(ThreadFunc func, PISystemTime loop_delay);
|
||||
|
||||
//! \~english Start thread
|
||||
//! \~russian Запускает поток
|
||||
//! \~english Stores a lambda callback and starts the thread.
|
||||
//! \~russian Сохраняет лямбда-обратный вызов и запускает поток.
|
||||
bool start(std::function<void()> func);
|
||||
|
||||
//! \~english Start thread
|
||||
//! \~russian Запускает поток
|
||||
//! \~english Stores a lambda callback and loop delay, then starts the thread.
|
||||
//! \~russian Сохраняет лямбда-обратный вызов и задержку цикла, затем запускает поток.
|
||||
bool start(std::function<void()> func, PISystemTime loop_delay);
|
||||
|
||||
//! \~english Start thread without internal loop
|
||||
//! \~russian Запускает поток без внутреннего цикла
|
||||
//! \~english Starts a one-shot thread without the repeating loop.
|
||||
//! \~russian Запускает одноразовый поток без повторяющегося цикла.
|
||||
bool startOnce();
|
||||
|
||||
//! \~english Start thread without internal loop
|
||||
//! \~russian Запускает поток без внутреннего цикла
|
||||
//! \~english Stores a callback and starts one-shot execution.
|
||||
//! \~russian Сохраняет обратный вызов и запускает одноразовое выполнение.
|
||||
bool startOnce(ThreadFunc func);
|
||||
|
||||
//! \~english Start thread without internal loop
|
||||
//! \~russian Запускает поток без внутреннего цикла
|
||||
//! \~english Stores a lambda callback and starts one-shot execution.
|
||||
//! \~russian Сохраняет лямбда-обратный вызов и запускает одноразовое выполнение.
|
||||
bool startOnce(std::function<void()> func);
|
||||
|
||||
EVENT_HANDLER0(void, stop);
|
||||
EVENT_HANDLER0(void, terminate);
|
||||
|
||||
//! \~english Deprecated overload of \a stopAndWait() that accepts milliseconds.
|
||||
//! \~russian Устаревшая перегрузка \a stopAndWait(), принимающая миллисекунды.
|
||||
bool stopAndWait(int timeout_ms) DEPRECATEDM("use stopAndWait(PISystemTime)") {
|
||||
return stopAndWait(PISystemTime::fromMilliseconds(timeout_ms));
|
||||
}
|
||||
|
||||
//! \~english Stop thread and wait for finish. Returns \b false if timeout expired.
|
||||
//! \~russian Останавливает поток и ожидает завершения. Возвращает \b false если таймаут истек.
|
||||
//! \~english Requests stop and waits for thread completion. Returns \b false if the timeout expires.
|
||||
//! \~russian Запрашивает остановку и ожидает завершения потока. Возвращает \b false, если таймаут истек.
|
||||
bool stopAndWait(PISystemTime timeout = {});
|
||||
|
||||
//! \~english Set common data passed to external function
|
||||
//! \~russian Устанавливает данные, передаваемые в функцию потока
|
||||
//! \~english Sets the data pointer passed to \a ThreadFunc callbacks.
|
||||
//! \~russian Устанавливает указатель данных, передаваемый в обратные вызовы \a ThreadFunc.
|
||||
void setData(void * d) { data_ = d; }
|
||||
|
||||
//! \~english Set external function that will be executed after every \a run()
|
||||
//! \~russian Устанавливает функцию потока, вызываемую после каждого \a run()
|
||||
//! \~english Sets the callback executed after each \a run() pass.
|
||||
//! \~russian Устанавливает обратный вызов, выполняемый после каждого прохода \a run().
|
||||
void setSlot(ThreadFunc func) { ret_func = func; }
|
||||
|
||||
//! \~english Set external function that will be executed after every \a run()
|
||||
//! \~russian Устанавливает функцию потока, вызываемую после каждого \a run()
|
||||
//! \~english Sets a lambda callback executed after each \a run() pass.
|
||||
//! \~russian Устанавливает лямбда-обратный вызов, выполняемый после каждого прохода \a run().
|
||||
void setSlot(std::function<void()> func) {
|
||||
ret_func = [func](void *) { func(); };
|
||||
}
|
||||
|
||||
//! \~english Set thread priority
|
||||
//! \~russian Устанавливает приоритет потока
|
||||
//! \~english Sets the priority hint. If the thread is already running, applies it immediately.
|
||||
//! \~russian Устанавливает подсказку приоритета. Если поток уже работает, применяет ее немедленно.
|
||||
void setPriority(PIThread::Priority prior);
|
||||
|
||||
//! \~english Returns common data passed to external function
|
||||
//! \~russian Возвращает данные, передаваемые в функцию потока
|
||||
//! \~english Returns the data pointer passed to \a ThreadFunc callbacks.
|
||||
//! \~russian Возвращает указатель данных, передаваемый в обратные вызовы \a ThreadFunc.
|
||||
void * data() const { return data_; }
|
||||
|
||||
//! \~english Return thread priority
|
||||
//! \~russian Возвращает приоритет потока
|
||||
//! \~english Returns the configured priority hint.
|
||||
//! \~russian Возвращает настроенную подсказку приоритета.
|
||||
PIThread::Priority priority() const { return priority_; }
|
||||
|
||||
//! \~english Return if thread is running
|
||||
//! \~russian Возвращает исполняется ли поток
|
||||
//! \~english Returns whether the thread is currently running.
|
||||
//! \~russian Возвращает, выполняется ли поток в данный момент.
|
||||
bool isRunning() const { return running_; }
|
||||
|
||||
//! \~english Return if thread is stopping
|
||||
//! \~russian Возвращает останавливается ли поток
|
||||
//! \~english Returns whether stop has been requested and the thread is still finishing.
|
||||
//! \~russian Возвращает, был ли запрошен останов и поток еще завершает работу.
|
||||
bool isStopping() const { return running_ && terminating; }
|
||||
|
||||
//! \~english Wait for thread start
|
||||
//! \~russian Ожидает старта потока
|
||||
//! \~english Waits until the thread starts. Returns \b false if the timeout expires first.
|
||||
//! \~russian Ожидает запуска потока. Возвращает \b false, если таймаут истек раньше.
|
||||
bool waitForStart(PISystemTime timeout = {});
|
||||
//! \~english Deprecated overload of \a waitForStart() that accepts milliseconds.
|
||||
//! \~russian Устаревшая перегрузка \a waitForStart(), принимающая миллисекунды.
|
||||
bool waitForStart(int timeout_msecs) DEPRECATEDM("use waitForStart(PISystemTime)") {
|
||||
return waitForStart(PISystemTime::fromMilliseconds(timeout_msecs));
|
||||
}
|
||||
|
||||
//! \~english Wait for thread finish. Returns \b false if timeout expired.
|
||||
//! \~russian Ожидает завершения потока. Возвращает \b false если таймаут истек.
|
||||
//! \~english Waits for thread completion. Returns \b false if the timeout expires first.
|
||||
//! \~russian Ожидает завершения потока. Возвращает \b false, если таймаут истек раньше.
|
||||
bool waitForFinish(PISystemTime timeout = {});
|
||||
//! \~english Deprecated overload of \a waitForFinish() that accepts milliseconds.
|
||||
//! \~russian Устаревшая перегрузка \a waitForFinish(), принимающая миллисекунды.
|
||||
bool waitForFinish(int timeout_msecs) DEPRECATEDM("use waitForFinish(PISystemTime)") {
|
||||
return waitForFinish(PISystemTime::fromMilliseconds(timeout_msecs));
|
||||
}
|
||||
|
||||
//! \~english Set necessity of lock every \a run() with internal mutex
|
||||
//! \~russian Устанавливает необходимость блокировки внутреннего мьютекса каждый \a run()
|
||||
//! \~english Enables locking of the internal mutex around \a begin(), \a run(), callbacks and \a end().
|
||||
//! \~russian Включает блокировку внутреннего мьютекса вокруг \a begin(), \a run(), обратных вызовов и \a end().
|
||||
void needLockRun(bool need) { lockRun = need; }
|
||||
|
||||
EVENT_HANDLER0(void, lock) const { thread_mutex.lock(); }
|
||||
EVENT_HANDLER0(void, unlock) const { thread_mutex.unlock(); }
|
||||
|
||||
//! \~english Returns internal mutex
|
||||
//! \~russian Возвращает внутренний мьютекс
|
||||
//! \~english Returns the internal mutex used by \a lock(), \a unlock() and \a needLockRun().
|
||||
//! \~russian Возвращает внутренний мьютекс, используемый \a lock(), \a unlock() и \a needLockRun().
|
||||
PIMutex & mutex() const { return thread_mutex; }
|
||||
|
||||
//! \~english Returns thread ID
|
||||
//! \~russian Возвращает ID потока
|
||||
//! \~english Returns the system thread identifier, or -1 when the thread is not running.
|
||||
//! \~russian Возвращает системный идентификатор потока, либо -1 когда поток не запущен.
|
||||
llong tid() const { return tid_; }
|
||||
|
||||
void __thread_func__();
|
||||
void __thread_func_once__();
|
||||
|
||||
EVENT(started);
|
||||
EVENT(stopped);
|
||||
|
||||
//! \~english Call event handler "handler" of object "object" in separate thread
|
||||
//! \~russian Вызывает обработчик "handler" объекта "object" в отдельном потоке
|
||||
//! \~english Creates a temporary thread and invokes handler \a handler of object \a object on it.
|
||||
//! \~russian Создает временный поток и вызывает в нем обработчик \a handler объекта \a object.
|
||||
static void runOnce(PIObject * object, const char * handler, const PIString & name = PIString());
|
||||
|
||||
//! \~english Call [lambda expression](https://en.cppreference.com/w/cpp/language/lambda) "func" in separate thread
|
||||
//! \~russian Вызывает [лямбда-выражение](https://ru.cppreference.com/w/cpp/language/lambda) "func" в отдельном потоке
|
||||
//! \~english Creates a temporary thread and runs [lambda expression](https://en.cppreference.com/w/cpp/language/lambda) \a func on it.
|
||||
//! \~russian Создает временный поток и выполняет в нем [лямбда-выражение](https://ru.cppreference.com/w/cpp/language/lambda) \a func.
|
||||
static void runOnce(std::function<void()> func, const PIString & name = PIString());
|
||||
|
||||
//! \handlers
|
||||
@@ -234,23 +261,27 @@ public:
|
||||
|
||||
//! \fn void stop()
|
||||
//! \brief
|
||||
//! \~english Stop thread
|
||||
//! \~russian Останавливает поток
|
||||
//! \~english Requests graceful thread shutdown.
|
||||
//! \~russian Запрашивает корректное завершение потока.
|
||||
EVENT_HANDLER0(void, stop);
|
||||
|
||||
//! \fn void terminate()
|
||||
//! \brief
|
||||
//! \~english Strongly stop thread
|
||||
//! \~russian Жёстко прерывает поток
|
||||
//! \~english Forces thread termination. Use only as a last resort.
|
||||
//! \~russian Принудительно прерывает поток. Используйте только как крайнюю меру.
|
||||
EVENT_HANDLER0(void, terminate);
|
||||
|
||||
//! \fn void lock()
|
||||
//! \brief
|
||||
//! \~english Lock internal mutex
|
||||
//! \~russian Блокирует внутренний мьютекс
|
||||
//! \~english Locks the internal mutex.
|
||||
//! \~russian Блокирует внутренний мьютекс.
|
||||
EVENT_HANDLER0(void, lock) const { thread_mutex.lock(); }
|
||||
|
||||
//! \fn void unlock()
|
||||
//! \brief
|
||||
//! \~english Unlock internal mutex
|
||||
//! \~russian Разблокирует внутренний мьютекс
|
||||
//! \~english Unlocks the internal mutex.
|
||||
//! \~russian Разблокирует внутренний мьютекс.
|
||||
EVENT_HANDLER0(void, unlock) const { thread_mutex.unlock(); }
|
||||
|
||||
//! \}
|
||||
//! \events
|
||||
@@ -258,29 +289,31 @@ public:
|
||||
|
||||
//! \fn void started()
|
||||
//! \brief
|
||||
//! \~english Raise on thread start
|
||||
//! \~russian Вызывается при старте потока
|
||||
//! \~english Raised after the thread has started.
|
||||
//! \~russian Вызывается после запуска потока.
|
||||
EVENT(started);
|
||||
|
||||
//! \fn void stopped()
|
||||
//! \brief
|
||||
//! \~english Raise on thread stop
|
||||
//! \~russian Вызывается при завершении потока
|
||||
//! \~english Raised when thread shutdown begins.
|
||||
//! \~russian Вызывается при начале завершения потока.
|
||||
EVENT(stopped);
|
||||
|
||||
//! \}
|
||||
|
||||
protected:
|
||||
static int priority2System(PIThread::Priority p);
|
||||
|
||||
//! \~english Function executed once at the start of thread
|
||||
//! \~russian Метод выполняется один раз при старте потока
|
||||
//! \~english Virtual method executed once after the system thread starts and before \a started().
|
||||
//! \~russian Виртуальный метод, выполняемый один раз после запуска системного потока и до \a started().
|
||||
virtual void begin() { ; }
|
||||
|
||||
//! \~english Function executed at every "loop_delay" msecs until thread was stopped
|
||||
//! \~russian Метод выполняется каждые "loop_delay" миллисекунд
|
||||
//! \~english Virtual method executed on each loop iteration until stop is requested.
|
||||
//! \~russian Виртуальный метод, выполняемый на каждой итерации цикла, пока не запрошен останов.
|
||||
virtual void run() { ; }
|
||||
|
||||
//! \~english Function executed once at the end of thread
|
||||
//! \~russian Метод выполняется один раз при остановке потока
|
||||
//! \~english Virtual method executed once during thread shutdown after \a stopped().
|
||||
//! \~russian Виртуальный метод, выполняемый один раз при завершении потока после \a stopped().
|
||||
virtual void end() { ; }
|
||||
|
||||
std::atomic_bool terminating, running_, lockRun;
|
||||
|
||||
Reference in New Issue
Block a user