merged AI doc, some new pages

libs/main/thread/pireadwritelock.h

@@ -1,13 +1,13 @@
 /*! \file pireadwritelock.h
- * \ingroup Read/Write lock
+ * \ingroup Thread
  * \~\brief
- * \~english Read/Write lock
- * \~russian Блокировка чтения/записи
+ * \~english Read-write lock with multiple readers or one writer
+ * \~russian Блокировка чтения-записи с несколькими читателями или одним писателем
  */
 /*
     PIP - Platform Independent Primitives
-	PIReadWriteLock, PIReadLocker, PIWriteLocker
-	Ivan Pelipenko peri4ko@yandex.ru
+    PIReadWriteLock, PIReadLocker, PIWriteLocker
+    Ivan Pelipenko peri4ko@yandex.ru
 
     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU Lesser General Public License as published by
@@ -28,7 +28,10 @@
 
 #include "piconditionvar.h"
 
-
+//! \~\ingroup Thread
+//! \~\brief
+//! \~english Synchronization primitive that allows concurrent readers and exclusive writer access.
+//! \~russian Примитив синхронизации, допускающий одновременных читателей и эксклюзивный доступ писателя.
 class PIP_EXPORT PIReadWriteLock {
 public:
 	NO_COPY_CLASS(PIReadWriteLock)
@@ -42,37 +45,37 @@ public:
 	~PIReadWriteLock();
 
 
-	//! \~english Lock for write. If already locked for write or read, than wait until all locks released.
-	//! \~russian Заблокировать на запись. Если уже заблокировано на запись или чтение, то ждёт освобождения блокировок.
+	//! \~english Acquires writer access, waiting until there are no active readers or writer.
+	//! \~russian Захватывает доступ на запись, ожидая отсутствия активных читателей и писателя.
 	void lockWrite();
 
-	//! \~english Try to lock for write. Returns if operation was successfull.
-	//! \~russian Пробует заблокировать на запись. Возвращает успех операции.
+	//! \~english Tries to acquire writer access without waiting.
+	//! \~russian Пытается захватить доступ на запись без ожидания.
 	bool tryLockWrite();
 
-	//! \~english Try to lock for write for \"timeout\". Returns if operation was successfull (timeout has not expired).
-	//! \~russian Пробует заблокировать на запись в течении \"timeout\". Возвращает успех операции (не истек ли тайм-аут).
+	//! \~english Tries to acquire writer access within \a timeout.
+	//! \~russian Пытается захватить доступ на запись в пределах \a timeout.
 	bool tryLockWrite(PISystemTime timeout);
 
-	//! \~english Release lock for write.
-	//! \~russian Освобождает блокировку на запись.
+	//! \~english Releases writer access and wakes waiting threads.
+	//! \~russian Освобождает доступ на запись и пробуждает ожидающие потоки.
 	void unlockWrite();
 
 
-	//! \~english Lock for read. If already locked for write, than wait until write lock released.
-	//! \~russian Заблокировать на чтение. Если уже заблокировано на запись, то ждёт освобождения записывающей блокировки.
+	//! \~english Acquires one reader slot, waiting while writer access is active.
+	//! \~russian Захватывает одно место читателя, ожидая пока активен доступ на запись.
 	void lockRead();
 
-	//! \~english Try to lock for read. Returns if operation was successfull.
-	//! \~russian Пробует заблокировать на чтение. Возвращает успех операции.
+	//! \~english Tries to acquire reader access without waiting.
+	//! \~russian Пытается захватить доступ на чтение без ожидания.
 	bool tryLockRead();
 
-	//! \~english Try to lock for read for \"timeout\". Returns if operation was successfull (timeout has not expired).
-	//! \~russian Пробует заблокировать на чтение в течении \"timeout\". Возвращает успех операции (не истек ли тайм-аут).
+	//! \~english Tries to acquire reader access within \a timeout.
+	//! \~russian Пытается захватить доступ на чтение в пределах \a timeout.
 	bool tryLockRead(PISystemTime timeout);
 
-	//! \~english Release lock for read.
-	//! \~russian Освобождает блокировку на чтение.
+	//! \~english Releases one reader slot and wakes waiting threads.
+	//! \~russian Освобождает одно место читателя и пробуждает ожидающие потоки.
 	void unlockRead();
 
 private:
@@ -82,7 +85,10 @@ private:
 	PIConditionVariable var;
 };
 
-
+//! \~\ingroup Thread
+//! \~\brief
+//! \~english Scope guard that acquires reader access in constructor and releases it in destructor.
+//! \~russian Защитник области видимости, который захватывает доступ на чтение в конструкторе и освобождает его в деструкторе.
 class PIP_EXPORT PIReadLocker {
 public:
 	NO_COPY_CLASS(PIReadLocker);
@@ -104,7 +110,10 @@ private:
 	bool cond = true;
 };
 
-
+//! \~\ingroup Thread
+//! \~\brief
+//! \~english Scope guard that acquires writer access in constructor and releases it in destructor.
+//! \~russian Защитник области видимости, который захватывает доступ на запись в конструкторе и освобождает его в деструкторе.
 class PIP_EXPORT PIWriteLocker {
 public:
 	NO_COPY_CLASS(PIWriteLocker);
@@ -127,4 +136,4 @@ private:
 };
 
 
-#endif
+#endif // PIREADWRITELOCK_H