merged AI doc, some new pages

2026-03-12 14:46:57 +03:00
parent 07ae277f9e
commit ed13838237
206 changed files with 14088 additions and 5152 deletions
--- a/libs/main/thread/piblockingqueue.h
+++ b/libs/main/thread/piblockingqueue.h
@@ -1,12 +1,11 @@
-/*! \file piblockingqueue.h
- * \ingroup Thread
- * \~\brief
- * \~english Queue with blocking
- * \~russian Блокирующая очередь
- */
+//! \~\file piblockingqueue.h
+//! \~\ingroup Thread
+//! \~\brief
+//! \~english Blocking queue template
+//! \~russian Шаблон блокирующей очереди
 /*
    PIP - Platform Independent Primitives
-
+	Blocking queue template
    Stephan Fomenko

    This program is free software: you can redistribute it and/or modify
@@ -29,16 +28,19 @@
 #include "piconditionvar.h"
 #include "piqueue.h"

-/**
- * \brief A Queue that supports operations that wait for the queue to become non-empty when retrieving an element, and
- * wait for space to become available in the queue when storing an element.
- */
+//! \~\ingroup Thread
+//! \~\brief
+//! \~english Thread-safe queue that supports blocking operations - waits for space when storing and waits for element when retrieving.
+//! \~russian Потокобезопасная очередь с поддержкой блокирующих операций - ожидает место при добавлении и ожидает элемент при получении.
 template<typename T>
 class PIBlockingQueue: private PIQueue<T> {
 public:
-	/**
-	 * \brief Constructor
-	 */
+	//! \~\brief
+	//! \~english Constructs queue with capacity \a capacity.
+	//! \~russian Создает очередь с емкостью \a capacity.
+	//! \~\details
+	//! \~english Passed condition variables become owned by the queue and are deleted with it.
+	//! \~russian Переданные переменные условия переходят во владение очереди и удаляются вместе с ней.
 	explicit inline PIBlockingQueue(size_t capacity                    = SIZE_MAX,
 	                                PIConditionVariable * cond_var_add = new PIConditionVariable(),
 	                                PIConditionVariable * cond_var_rem = new PIConditionVariable())
@@ -46,9 +48,8 @@ public:
 		, cond_var_rem(cond_var_rem)
 		, max_size(capacity) {}

-	/**
-	 * \brief Copy constructor. Initialize queue with copy of other queue elements. Not thread-safe for other queue.
-	 */
+	//! \~english Constructs queue from snapshot of \a other without synchronizing access to the source deque.
+	//! \~russian Создает очередь из снимка \a other без синхронизации доступа к исходной очереди.
 	explicit inline PIBlockingQueue(const PIDeque<T> & other)
 		: cond_var_add(new PIConditionVariable())
 		, cond_var_rem(new PIConditionVariable()) {
@@ -58,9 +59,8 @@ public:
 		mutex.unlock();
 	}

-	/**
-	 * \brief Thread-safe copy constructor. Initialize queue with copy of other queue elements.
-	 */
+	//! \~english Constructs queue by copying another blocking queue while locking both queues.
+	//! \~russian Создает очередь копированием другой блокирующей очереди с блокировкой обеих очередей.
 	inline PIBlockingQueue(PIBlockingQueue<T> & other): cond_var_add(new PIConditionVariable()), cond_var_rem(new PIConditionVariable()) {
 		other.mutex.lock();
 		mutex.lock();
@@ -70,16 +70,16 @@ public:
 		other.mutex.unlock();
 	}

+	//! \~english Destroys queue and owned condition variables.
+	//! \~russian Уничтожает очередь и принадлежащие ей переменные условия.
 	~PIBlockingQueue() {
 		delete cond_var_add;
 		delete cond_var_rem;
 	}

-	/**
-	 * \brief Inserts the specified element into this queue, waiting if necessary for space to become available.
-	 *
-	 * @param v the element to add
-	 */
+
+	//! \~english Appends \a v, waiting indefinitely until space becomes available when the queue is full.
+	//! \~russian Добавляет \a v в конец, ожидая без ограничения по времени появления свободного места при заполненной очереди.
 	PIBlockingQueue<T> & put(const T & v) {
 		mutex.lock();
 		cond_var_rem->wait(mutex, [&]() { return PIDeque<T>::size() < max_size; });
@@ -89,16 +89,18 @@ public:
 		return *this;
 	}

+	//! \~english Alias for \a put().
+	//! \~russian Псевдоним для \a put().
 	PIBlockingQueue<T> & enqueue(const T & v) { return put(v); }

-	/**
-	 * \brief Inserts the specified element at the end of this queue if it is possible to do so immediately without
-	 * exceeding the queue's capacity, returning true upon success and false if this queue is full.
-	 *
-	 * @param v the element to add
-	 * @param timeout the timeout waiting for inserting if que is full, if timeout is null, then returns immediately
-	 * @return true if the element was added to this queue, else false
-	 */
+	//! \~\brief
+	//! \~english Tries to append \a v.
+	//! \~russian Пытается добавить \a v в конец очереди.
+	//! \~\details
+	//! \~english
+	//! With null \a timeout this method checks capacity once and returns immediately.
+	//! \~russian
+	//! При пустом \a timeout метод однократно проверяет емкость и возвращается сразу.
 	bool offer(const T & v, PISystemTime timeout = {}) {
 		bool isOk;
 		mutex.lock();
@@ -112,11 +114,9 @@ public:
 		return isOk;
 	}

-	/**
-	 * \brief Retrieves and removes the head of this queue, waiting if necessary until an element becomes available.
-	 *
-	 * @return the head of this queue
-	 */
+
+	//! \~english Removes and returns the front element, waiting indefinitely until one becomes available.
+	//! \~russian Удаляет и возвращает элемент из начала очереди, ожидая его появления без ограничения по времени.
 	T take() {
 		T t;
 		mutex.lock();
@@ -127,18 +127,21 @@ public:
 		return t;
 	}

+	//! \~english Alias for \a take().
+	//! \~russian Псевдоним для \a take().
 	T dequeue() { return take(); }

-	/**
-	 * \brief Retrieves and removes the head of this queue, waiting up to the specified wait time if necessary for an
-	 * element to become available.
-	 *
-	 * @param timeout how long to wait before giving up
-	 * @param defaultVal value, which returns if the specified waiting time elapses before an element is available
-	 * @param isOk flag, which indicates result of method execution. It will be set to false if timeout, or true if
-	 * return value is retrieved value
-	 * @return the head of this queue, or defaultVal if the specified waiting time elapses before an element is available
-	 */
+
+	//! \~\brief
+	//! \~english Tries to remove and return the front element.
+	//! \~russian Пытается удалить и вернуть элемент из начала очереди.
+	//! \~\details
+	//! \~english
+	//! With null \a timeout this method checks once and returns \a defaultVal immediately if the queue is empty.
+	//! If \a isOk is not null, it is set to \c true on successful retrieval.
+	//! \~russian
+	//! При пустом \a timeout метод проверяет очередь один раз и сразу возвращает \a defaultVal, если очередь пуста.
+	//! \Если \a isOk не равен null, он получает значение \c true при успешном извлечении.
 	T poll(PISystemTime timeout = {}, const T & defaultVal = T(), bool * isOk = nullptr) {
 		T t = defaultVal;
 		bool isNotEmpty;
@@ -154,12 +157,15 @@ public:
 		return t;
 	}

-	/**
-	 * \brief Returns the number of elements that this queue can ideally (in the absence of memory or resource
-	 * constraints) contains. This is always equal to the initial capacity of this queue less the current size of this queue.
-	 *
-	 * @return the capacity
-	 */
+
+	//! \~\brief
+	//! \~english Returns configured capacity limit.
+	//! \~russian Возвращает настроенный предел емкости.
+	//! \~\details
+	//! \~english
+	//! For the default unbounded queue this value is \c SIZE_MAX.
+	//! \~russian
+	//! Для очереди без ограничения по умолчанию это значение равно \c SIZE_MAX.
 	size_t capacity() {
 		size_t c;
 		mutex.lock();
@@ -168,12 +174,8 @@ public:
 		return c;
 	}

-	/**
-	 * \brief Returns the number of additional elements that this queue can ideally (in the absence of memory or resource
-	 * constraints) accept. This is always equal to the initial capacity of this queue less the current size of this queue.
-	 *
-	 * @return the remaining capacity
-	 */
+	//! \~english Returns how many more elements can be inserted without blocking at the moment of the call.
+	//! \~russian Возвращает, сколько элементов еще можно вставить без блокировки в момент вызова.
 	size_t remainingCapacity() {
 		mutex.lock();
 		size_t c = max_size - PIDeque<T>::size();
@@ -181,9 +183,8 @@ public:
 		return c;
 	}

-	/**
-	 * \brief Returns the number of elements in this collection.
-	 */
+	//! \~english Returns current number of queued elements.
+	//! \~russian Возвращает текущее количество элементов в очереди.
 	size_t size() {
 		mutex.lock();
 		size_t s = PIDeque<T>::size();
@@ -191,9 +192,9 @@ public:
 		return s;
 	}

-	/**
-	 * \brief Removes all available elements from this queue and adds them to other given queue.
-	 */
+
+	//! \~english Moves up to \a maxCount currently available elements into deque \a other without waiting.
+	//! \~russian Перемещает до \a maxCount доступных в данный момент элементов в деку \a other без ожидания.
 	size_t drainTo(PIDeque<T> & other, size_t maxCount = SIZE_MAX) {
 		mutex.lock();
 		size_t count = ((maxCount > PIDeque<T>::size()) ? PIDeque<T>::size() : maxCount);
@@ -203,9 +204,14 @@ public:
 		return count;
 	}

-	/**
-	 * \brief Removes all available elements from this queue and adds them to other given queue.
-	 */
+	//! \~\brief
+	//! \~english Moves up to \a maxCount currently available elements into blocking queue \a other without waiting.
+	//! \~russian Перемещает до \a maxCount доступных в данный момент элементов в блокирующую очередь \a other без ожидания.
+	//! \~\details
+	//! \~english
+	//! The actual count is also limited by the remaining capacity of \a other.
+	//! \~russian
+	//! Фактическое количество также ограничено оставшейся емкостью \a other.
 	size_t drainTo(PIBlockingQueue<T> & other, size_t maxCount = SIZE_MAX) {
 		mutex.lock();
 		other.mutex.lock();