mdbx: description of internal lck API.

Change-Id: Ic677ba62ca566409a44234a1c0d8b0b41158fe86

src/osal.h

@@ -599,21 +599,82 @@ void mdbx_osal_jitter(bool tiny);
 #define MDBX_OSAL_LOCK_SIZE 0
 #endif /* MDBX_OSAL_LOCK_SIZE */
 
+/// \brief Инициализация объектов синхронизации внутри текущего процесса
+///   связанных с экземпляром MDBX_env.
+/// \return Код ошибки или 0 в случае успеха.
 int mdbx_lck_init(MDBX_env *env);
 
-int mdbx_lck_seize(MDBX_env *env);
-int mdbx_lck_downgrade(MDBX_env *env, bool complete);
+/// \brief Отключение от общих межпроцесных объектов и разрушение объектов
+///   синхронизации внутри текущего процесса связанных с экземпляром MDBX_env.
 void mdbx_lck_destroy(MDBX_env *env);
 
+/// \brief Подключение к общим межпроцесным объектам блокировки с попыткой
+///   захвата блокировки максимального уровня (разделяемой при недоступности
+///   эксклюзивной).
+///   В зависимости от реализации и/или платформы (Windows) может
+///   захватывать блокировку не-операционного супер-уровня (например, для
+///   инициализации разделяемых объектов синхронизации), которая затем будет
+///   понижена до операционно-эксклюзивной или разделяемой посредством
+///   явного вызова mdbx_lck_downgrade().
+/// \return
+///   MDBX_RESULT_TRUE (-1) - если удалось захватить эксклюзивную блокировку и,
+///     следовательно, текущий процесс является первым и единственным
+///     после предыдущего использования БД.
+///   MDBX_RESULT_FALSE (0) - если удалось захватить только разделяемую
+///     блокировку и, следовательно, БД уже открыта и используется другими
+///     процессами.
+///   Иначе (не 0 и не -1) - код ошибки.
+int mdbx_lck_seize(MDBX_env *env);
+
+/// \brief Снижает уровень первоначальной захваченной блокировки до
+///   операционного уровня определяемого аргументом.
+/// \param
+///   complete = TRUE - понижение до разделяемой блокировки.
+///   complete = FALSE - понижение до эксклюзивной операционной блокировки.
+/// \return Код ошибки или 0 в случае успеха.
+int mdbx_lck_downgrade(MDBX_env *env, bool complete);
+
+/// \brief Блокирует lck-файл и/или таблицу читателей для (де)регистрации.
+/// \return Код ошибки или 0 в случае успеха.
 int mdbx_rdt_lock(MDBX_env *env);
+
+/// \brief Разблокирует lck-файл и/или таблицу читателей после (де)регистрации.
 void mdbx_rdt_unlock(MDBX_env *env);
 
+/// \brief Захватывает блокировку для изменения БД (при старте пишущей
+/// транзакции). Транзакции чтения при этом никак не блокируются.
+/// \return Код ошибки или 0 в случае успеха.
 LIBMDBX_API int mdbx_txn_lock(MDBX_env *env, bool dontwait);
+
+/// \brief Освобождает блокировку по окончанию изменения БД (после завершения
+/// пишущей транзакции).
 LIBMDBX_API void mdbx_txn_unlock(MDBX_env *env);
 
+/// \brief Устанавливает alive-флажок присутствия (индицирующую блокировку)
+///   читателя для pid текущего процесса. Функции может выполнить не более
+///   необходимого минимума для корректной работы mdbx_rpid_check() в других
+///   процессах.
+/// \return Код ошибки или 0 в случае успеха.
 int mdbx_rpid_set(MDBX_env *env);
+
+/// \brief Снимает alive-флажок присутствия (индицирующую блокировку)
+///   читателя для pid текущего процесса. Функции может выполнить не более
+///   необходимого минимума для корректной работы mdbx_rpid_check() в других
+///   процессах.
+/// \return Код ошибки или 0 в случае успеха.
 int mdbx_rpid_clear(MDBX_env *env);
 
+/// \brief Проверяет жив ли процесс-читатель с заданным pid
+///   по alive-флажку присутствия (индицирующей блокировку),
+///   либо любым другим способом.
+/// \return
+///   MDBX_RESULT_TRUE (-1) - если процесс-читатель с соответствующим pid жив
+///     и работает с БД (индицирующая блокировка присутствует).
+///   MDBX_RESULT_FALSE (0) - если процесс-читатель с соответствующим pid
+///     отсутствует или не работает с БД (индицирующая блокировка отсутствует).
+///   Иначе (не 0 и не -1) - код ошибки.
+int mdbx_rpid_check(MDBX_env *env, mdbx_pid_t pid);
+
 #if defined(_WIN32) || defined(_WIN64)
 typedef union MDBX_srwlock {
   struct {
@@ -665,14 +726,6 @@ extern MDBX_NtFsControlFile mdbx_NtFsControlFile;
 
 #endif /* Windows */
 
-/* Checks reader by pid.
- *
- * Returns:
- *   MDBX_RESULT_TRUE, if pid is live (unable to acquire lock)
- *   MDBX_RESULT_FALSE, if pid is dead (lock acquired)
- *   or otherwise the errcode. */
-int mdbx_rpid_check(MDBX_env *env, mdbx_pid_t pid);
-
 /*----------------------------------------------------------------------------*/
 /* Atomics */