mdbx: English translation for osal.h

Change-Id: Iec7c3334f1866df243e7fcec89858ef37415a4a2

AUTHORS

@@ -29,3 +29,4 @@ Quanah Gibson-Mount <quanah@openldap.org>
 Salvador Ortiz <sog@msg.com.mx>
 Sebastien Launay <sebastien@slaunay.fr>
 Vladimir Romanov <vromanov@gmail.com>
+Zano Foundation <crypto.sowle@gmail.com>

src/elements/osal.h

@@ -659,115 +659,107 @@ MDBX_INTERNAL_FUNC uint32_t mdbx_osal_monotime_to_16dot16(uint64_t monotime);
 #define MDBX_OSAL_LOCK_SIGN UINT32_C(0x8017)
 #endif /* MDBX_OSAL_LOCK */
 
-/// \brief Инициализация объектов синхронизации связанных с экземпляром MDBX_env
+/// \brief Initialization of synchronization primitives linked with MDBX_env
-///   как общик в LCK-файле, так и внутри текущего процесса.
+///   instance both in LCK-file and within the current process.
 /// \param
-///   global_uniqueness_flag = true - означает что сейчас в системе нет других
+///   global_uniqueness_flag = true - denotes that there are no other processes
-///     процессов работающих с БД и LCK-файлом. Соответственно функция ДОЛЖНА
+///     working with DB and LCK-file. Thus the function MUST initialize
-///     инициализировать разделяемые объекты синхронизации расположенные
+///     shared synchronization objects in memory-mapped LCK-file.
-///     в отображенном в память LCK-файле.
+///   global_uniqueness_flag = false - denotes that at least one process is
-///   global_uniqueness_flag = false - означает что в системе есть хотя-бы
+///     already working with DB and LCK-file, including the case when DB
-///     один другой процесс уже работающий с БД и LCK-файлом, в том числе
+///     has already been opened in the current process. Thus the function
-///     БД уже может быть открыта текущим процессом. Соответственно функция
+///     MUST NOT initialize shared synchronization objects in memory-mapped
-///     НЕ должна инициализировать уже используемые разделяемые объекты
+///     LCK-file that are already in use.
-///     синхронизации расположенные в отображенном в память LCK-файле.
+/// \return Error code or zero on success.
-/// \return Код ошибки или 0 в случае успеха.
 MDBX_INTERNAL_FUNC int mdbx_lck_init(MDBX_env *env,
                                      MDBX_env *inprocess_neighbor,
                                      int global_uniqueness_flag);
 
-/// \brief Отключение от общих межпроцесных объектов и разрушение объектов
+/// \brief Disconnects from shared interprocess objects and destructs
-///   синхронизации внутри текущего процесса связанных с экземпляром MDBX_env.
+///   synchronization objects linked with MDBX_env instance
+///   within the current process.
 /// \param
-///   inprocess_neighbor = NULL - если в текущем процессе нет других экземпляров
+///   inprocess_neighbor = NULL - if the current process does not have other
-///     MDBX_env связанных с закрываемой БД. Соответственно функция ДОЛЖНА
+///     instances of MDBX_env linked with the DB being closed.
-///     своими средствами проверить, есть ли другие процесса работающие с БД
+///     Thus the function MUST check for other processes working with DB or
-///     и LCK-файлом, и в зависимости от этого разрушить или сохранить бъекты
+///     LCK-file, and keep or destroy shared synchronization objects in
-///     синхронизации расположенные в отображенном в память LCK-файле.
+///     memory-mapped LCK-file depending on the result.
-///   inprocess_neighbor = не-NULL - тогда он указывает на другой (любой
+///   inprocess_neighbor = not-NULL - pointer to another instance of MDBX_env
-///     в случае нескольких) экземпляр MDBX_env работающей с БД и LCK-файлом
+///     (anyone of there is several) working with DB or LCK-file within the
-///     внутри текущего процесса. Соответственно, функция НЕ должна пытаться
+///     current process. Thus the function MUST NOT try to acquire exclusive
-///     захватывать эксклюзивную блокировки и/или пытаться разрушить общие
+///     lock and/or try to destruct shared synchronization objects linked with
-///     объекты синхронизации связанные с БД и LCK-файлом. Кроме этого,
+///     DB or LCK-file. Moreover, the implementation MUST ensure correct work
-///     реализация ДОЛЖНА обеспечить корректность работы других экземпляров
+///     of other instances of MDBX_env within the current process, e.g.
-///     MDBX_env внутри процесса - например, восстановить POSIX-fcntl блокировки
+///     restore POSIX-fcntl locks after the closing of file descriptors.
-///     после закрытия файловых дескрипторов.
+/// \return Error code (MDBX_PANIC) or zero on success.
-/// \return Код ошибки (MDBX_PANIC) или 0 в случае успеха.
 MDBX_INTERNAL_FUNC int mdbx_lck_destroy(MDBX_env *env,
                                         MDBX_env *inprocess_neighbor);
 
-/// \brief Подключение к общим межпроцесным объектам блокировки с попыткой
+/// \brief Connects to shared interprocess locking objects and tries to acquire
-///   захвата блокировки максимального уровня (разделяемой при недоступности
+///   the maximum lock level (shared if exclusive is not available)
-///   эксклюзивной).
+///   Depending on implementation or/and platform (Windows) this function may
-///   В зависимости от реализации и/или платформы (Windows) может
+///   acquire the non-OS super-level lock (e.g. for shared synchronization
-///   захватывать блокировку не-операционного супер-уровня (например, для
+///   objects initialization), which will be downgraded to OS-exclusive or
-///   инициализации разделяемых объектов синхронизации), которая затем будет
+///   shared via explicit calling of mdbx_lck_downgrade().
-///   понижена до операционно-эксклюзивной или разделяемой посредством
-///   явного вызова mdbx_lck_downgrade().
 /// \return
-///   MDBX_RESULT_TRUE (-1) - если удалось захватить эксклюзивную блокировку и,
+///   MDBX_RESULT_TRUE (-1) - if an exclusive lock was acquired and thus
-///     следовательно, текущий процесс является первым и единственным
+///     the current process is the first and only after the last use of DB.
-///     после предыдущего использования БД.
+///   MDBX_RESULT_FALSE (0) - if a shared lock was acquired and thus
-///   MDBX_RESULT_FALSE (0) - если удалось захватить только разделяемую
+///     DB has already been opened and now is used by other processes.
-///     блокировку и, следовательно, БД уже открыта и используется другими
+///   Otherwise (not 0 and not -1) - error code.
-///     процессами.
-///   Иначе (не 0 и не -1) - код ошибки.
 MDBX_INTERNAL_FUNC int mdbx_lck_seize(MDBX_env *env);
 
-/// \brief Снижает уровень первоначальной захваченной блокировки до
+/// \brief Downgrades the level of initially acquired lock to
-///   операционного уровня определяемого аргументом. Смысл функции в возврате
+///   operational level specified by agrument. The reson for such downgrade:
-///   в операционный режим:
+///    - unblocking of other processes that are waiting for access, i.e.
-///    - разблокирование других процессов ожидающих доступа, т.е если
+///      if (env->me_flags & MDBX_EXCLUSIVE) != 0, then other processes
-///      (env->me_flags & MDBX_EXCLUSIVE) != 0, то другие процессы должны узнать
+///      should be made aware that access is unavailable rather than
-///      о невозможности доступа, а не ждать его.
+///      wait for it.
-///    - снятия блокировок мешающих работе с файлом (актуально для Windows).
+///    - freeing locks that interfere file operation (expecially for Windows)
-///   (env->me_flags & MDBX_EXCLUSIVE) == 0 - понижение до разделяемой
+///   (env->me_flags & MDBX_EXCLUSIVE) == 0 - downgrade to shared lock.
-///   блокировки. (env->me_flags & MDBX_EXCLUSIVE) != 0 - понижение до
+///   (env->me_flags & MDBX_EXCLUSIVE) != 0 - downgrade to exclusive
-///   эксклюзивной операционной блокировки.
+///   operational lock.
-/// \return Код ошибки или 0 в случае успеха.
+/// \return Error code or zero on success
 MDBX_INTERNAL_FUNC int mdbx_lck_downgrade(MDBX_env *env);
 
-/// \brief Блокирует lck-файл и/или таблицу читателей для (де)регистрации.
+/// \brief Locks LCK-file or/and table of readers for (de)registering.
-/// \return Код ошибки или 0 в случае успеха.
+/// \return Error code or zero on success
 MDBX_INTERNAL_FUNC int mdbx_rdt_lock(MDBX_env *env);
 
-/// \brief Разблокирует lck-файл и/или таблицу читателей после (де)регистрации.
+/// \brief Unlocks LCK-file or/and table of readers after (de)registering.
 MDBX_INTERNAL_FUNC void mdbx_rdt_unlock(MDBX_env *env);
 
-/// \brief Захватывает блокировку для изменения БД (при старте пишущей
+/// \brief Acquires lock for DB change (on writing transaction start)
-///   транзакции). Транзакции чтения при этом никак не блокируются.
+///   Reading transactions will not be blocked.
-///   Объявлена LIBMDBX_API так как используется в mdbx_chk.
+///   Declared as LIBMDBX_API because it is used in mdbx_chk.
-/// \return Код ошибки или 0 в случае успеха.
+/// \return Error code or zero on success
 LIBMDBX_API int mdbx_txn_lock(MDBX_env *env, bool dontwait);
 
-/// \brief Освобождает блокировку по окончанию изменения БД (после завершения
+/// \brief Releases lock once DB changes is made (after writing transaction
-///   пишущей транзакции).
+///   has finished).
-///   Объявлена LIBMDBX_API так как используется в mdbx_chk.
+///   Declared as LIBMDBX_API because it is used in mdbx_chk.
 LIBMDBX_API void mdbx_txn_unlock(MDBX_env *env);
 
-/// \brief Устанавливает alive-флажок присутствия (индицирующую блокировку)
+/// \brief Sets alive-flag of reader presence (indicative lock) for PID of
-///   читателя для pid текущего процесса. Функции может выполнить не более
+///   the current process. The function does no more than needed for
-///   необходимого минимума для корректной работы mdbx_rpid_check() в других
+///   the correct working of mdbx_rpid_check() in other processes.
-///   процессах.
+/// \return Error code or zero on success
-/// \return Код ошибки или 0 в случае успеха.
 MDBX_INTERNAL_FUNC int mdbx_rpid_set(MDBX_env *env);
 
-/// \brief Снимает alive-флажок присутствия (индицирующую блокировку)
+/// \brief Resets alive-flag of reader presence (indicative lock)
-///   читателя для pid текущего процесса. Функции может выполнить не более
+///   for PID of the current process. The function does no more than needed
-///   необходимого минимума для корректной работы mdbx_rpid_check() в других
+///   for the correct working of mdbx_rpid_check() in other processes.
-///   процессах.
+/// \return Error code or zero on success
-/// \return Код ошибки или 0 в случае успеха.
 MDBX_INTERNAL_FUNC int mdbx_rpid_clear(MDBX_env *env);
 
-/// \brief Проверяет жив ли процесс-читатель с заданным pid
+/// \brief Checks for reading process status with the given pid with help of
-///   по alive-флажку присутствия (индицирующей блокировку),
+///   alive-flag of presence (indicative lock) or using another way.
-///   либо любым другим способом.
 /// \return
-///   MDBX_RESULT_TRUE (-1) - если процесс-читатель с соответствующим pid жив
+///   MDBX_RESULT_TRUE (-1) - if the reader process with the given PID is alive
-///     и работает с БД (индицирующая блокировка присутствует).
+///     and working with DB (indicative lock is present).
-///   MDBX_RESULT_FALSE (0) - если процесс-читатель с соответствующим pid
+///   MDBX_RESULT_FALSE (0) - if the reader process with the given PID is absent
-///     отсутствует или не работает с БД (индицирующая блокировка отсутствует).
+///     or not working with DB (indicative lock is not present).
-///   Иначе (не 0 и не -1) - код ошибки.
+///   Otherwise (not 0 and not -1) - error code.
 MDBX_INTERNAL_FUNC int mdbx_rpid_check(MDBX_env *env, uint32_t pid);
 
 #if defined(_WIN32) || defined(_WIN64)