merged AI doc, some new pages

libs/main/thread/pithreadpoolexecutor.h

@@ -1,3 +1,12 @@
+//! \~\file pithreadpoolexecutor.h
+//! \~\ingroup Thread
+//! \brief
+//! \~english Thread pool executor
+//! \~russian Исполнитель пула потоков
+//!
+//! \details
+//! \~english Executes tasks in a pool of worker threads.
+//! \~russian Выполняет задачи в пуле рабочих потоков.
 /*
     PIP - Platform Independent Primitives
 
@@ -26,28 +35,55 @@
 #include <atomic>
 
 
+//! \~\ingroup Thread
+//! \~\brief
+//! \~english Fixed-size pool of worker threads for fire-and-forget tasks.
+//! \~russian Фиксированный пул рабочих потоков для задач без ожидания результата.
 class PIP_EXPORT PIThreadPoolExecutor {
 public:
+	//! \~english Constructs executor with \a corePoolSize worker threads.
+	//! \~russian Создает исполнитель с \a corePoolSize рабочими потоками.
 	explicit PIThreadPoolExecutor(int corePoolSize);
 
+	//! \~english Stops worker threads and destroys executor resources.
+	//! \~russian Останавливает рабочие потоки и уничтожает ресурсы исполнителя.
 	virtual ~PIThreadPoolExecutor();
 
-	//! \brief Executes the given task sometime in the future. The task execute in an existing pooled thread. If the task
-	//! cannot be submitted for execution, either because this executor has been shutdown or because its capacity has been
-	//! reached.
-	//!
-	//! \param runnable not empty function for thread pool execution
+	//! \~\brief
+	//! \~english Submits \a runnable for asynchronous execution by a worker thread.
+	//! \~russian Передает \a runnable на асинхронное выполнение рабочим потоком.
+	//! \details
+	//! \~english
+	//! This is a best-effort fire-and-forget call and does not report whether the task was accepted.
+	//! \After shutdown requests new tasks are ignored.
+	//! \~russian
+	//! Это вызов по принципу best-effort без ожидания результата и без сообщения о том, была ли задача принята.
+	//! \После запроса на завершение новые задачи игнорируются.
 	void execute(const std::function<void()> & runnable);
 
+	//! \~english Requests immediate shutdown and stops worker threads without waiting for queued tasks to finish.
+	//! \~russian Запрашивает немедленное завершение и останавливает рабочие потоки без ожидания завершения задач в очереди.
 	void shutdownNow();
 
-	//! \brief Initiates an orderly shutdown in which previously submitted tasks are executed, but no new tasks will be
-	//! accepted. Invocation has no additional effect if already shut down. This method does not wait for previously
-	//! submitted tasks to complete execution. Use awaitTermination to do that.
+	//! \~\brief
+	//! \~english Requests orderly shutdown: new tasks are rejected and workers stop after the current queue is drained.
+	//! \~russian Запрашивает упорядоченное завершение: новые задачи отклоняются, а рабочие потоки останавливаются после опустошения текущей
+	//! очереди.
+	//! \details
+	//! \~english This method does not wait for worker termination.
+	//! \~russian Этот метод не ожидает завершения рабочих потоков.
 	void shutdown();
 
+	//! \~english Returns \c true after \a shutdown() or \a shutdownNow() has been requested.
+	//! \~russian Возвращает \c true после запроса \a shutdown() или \a shutdownNow().
 	bool isShutdown() const;
 
+	//! \~\brief
+	//! \~english Waits up to \a timeout for all worker threads to finish.
+	//! \~russian Ожидает до \a timeout завершения всех рабочих потоков.
+	//! \return
+	//! \~english \c false if the timeout expires first.
+	//! \~russian \c false, если таймаут истек раньше.
 	bool awaitTermination(PISystemTime timeout);
 
 private: