merged AI doc, some new pages

libs/main/thread/pispinlock.h

@@ -1,9 +1,8 @@
-/*! \file pispinlock.h
- * \ingroup Thread
- * \~\brief
- * \~english Fast and full-load lock
- * \~russian Быстрая блокировка с полной нагрузкой
- */
+//! \~\file pispinlock.h
+//! \~\ingroup Thread
+//! \~\brief
+//! \~english Spinlock with busy waiting
+//! \~russian Спинлок с активным ожиданием
 /*
     PIP - Platform Independent Primitives
     PISpinlock
@@ -31,6 +30,10 @@
 #include <atomic>
 
 
+//! \~\ingroup Thread
+//! \~\brief
+//! \~english Lock based on atomic spinning for very short critical sections.
+//! \~russian Блокировка на основе атомарного вращения для очень коротких критических секций.
 class PIP_EXPORT PISpinlock {
 public:
 	NO_COPY_CLASS(PISpinlock);
@@ -44,27 +47,15 @@ public:
 	~PISpinlock() {}
 
 
-	//! \~english Lock spinlock
-	//! \~russian Блокирует спинлок
-	//! \~\details
-	//! \~english
-	//! If spinlock is unlocked it set to locked state and returns immediate.
-	//! If spinlock is already locked function blocks until spinlock will be unlocked
-	//! \~russian
-	//! Если спинлок свободен, то блокирует его и возвращает управление немедленно.
-	//! Если спинлок заблокирован, то ожидает разблокировки, затем блокирует и возвращает управление
+	//! \~english Acquires the spinlock, busy-waiting until it becomes free.
+	//! \~russian Захватывает спинлок, активно ожидая его освобождения.
 	void lock() {
 		while (flag.test_and_set(std::memory_order_acquire))
 			;
 	}
 
-	//! \~english Unlock spinlock
-	//! \~russian Разблокирует спинлок
-	//! \~\details
-	//! \~english
-	//! In any case this function returns immediate
-	//! \~russian
-	//! В любом случае возвращает управление немедленно
+	//! \~english Releases the spinlock.
+	//! \~russian Освобождает спинлок.
 	void unlock() { flag.clear(std::memory_order_release); }
 
 private:
@@ -72,18 +63,22 @@ private:
 };
 
 
+//! \~\ingroup Thread
+//! \~\brief
+//! \~english Scope guard that locks a %PISpinlock in constructor and unlocks it in destructor.
+//! \~russian Защитник области видимости, который блокирует %PISpinlock в конструкторе и разблокирует его в деструкторе.
 class PIP_EXPORT PISpinlockLocker {
 public:
 	NO_COPY_CLASS(PISpinlockLocker);
 
 	//! \~english Constructs and lock "s" if "condition" is \c true
-	//! \~russianСоздает и блокирует спинлок "m" если "condition" \c true
+	//! \~russian Создает и блокирует спинлок "s" если "condition" \c true
 	PISpinlockLocker(PISpinlock & s, bool condition = true): spinlock(s), cond(condition) {
 		if (cond) spinlock.lock();
 	}
 
 	//! \~english Unlock "s" if "condition" was \c true
-	//! \~russian Разблокирует спинлок "m" если "condition" был \c true
+	//! \~russian Разблокирует спинлок "s" если "condition" был \c true
 	~PISpinlockLocker() {
 		if (cond) spinlock.unlock();
 	}