mdbx-doc: документирование mdbx_env_resurrect_after_fork().

docs/_restrictions.md

@@ -106,6 +106,7 @@ reservation can deplete system resources (trigger ENOMEM error, etc)
 when setting an inadequately large upper DB size using \ref
 mdbx_env_set_geometry() or \ref mdbx::env::geometry. So just avoid this.
 
+
 ## Remote filesystems
 Do not use MDBX databases on remote filesystems, even between processes
 on the same host. This breaks file locks on some platforms, possibly
@@ -132,6 +133,11 @@ corruption in such cases.
 On the other hand, MDBX allow calling \ref mdbx_env_close() in such cases to
 release resources, but no more and in general this is a wrong way.
 
+#### Since v0.13.1 and later
+Начиная с версии 0.13.1 в API доступна функция \ref mdbx_env_resurrect_after_fork(),
+которая позволяет пере-использовать в дочерних процессах уже открытую среду БД,
+но строго без наследования транзакций от родительского процесса.
+
 
 ## Read-only mode
 There is no pure read-only mode in a normal explicitly way, since

mdbx.h

@@ -2944,8 +2944,80 @@ LIBMDBX_INLINE_API(int, mdbx_env_close, (MDBX_env * env)) {
   return mdbx_env_close_ex(env, false);
 }
 
-#if !(defined(_WIN32) || defined(_WIN64))
+#if defined(DOXYGEN) || !(defined(_WIN32) || defined(_WIN64))
-/** FIXME */
+/** \brief Восстанавливает экземпляр среды в дочернем процессе после ветвления
+ * родительского процесса посредством `fork()` и родственных системных вызовов.
+ * \ingroup c_extra
+ *
+ * Без вызова \ref mdbx_env_resurrect_after_fork() использование открытого
+ * экземпляра среды в дочернем процессе не возможно, включая все выполняющиеся
+ * на момент ветвления транзакции.
+ *
+ * Выполняемые функцией действия можно рассматривать как повторное открытие БД
+ * в дочернем процессе, с сохранением заданных опций и адресов уже созданных
+ * экземпляров объектов связанных с API.
+ *
+ * \note Функция не доступна в ОС семейства Windows по причине отсутствия
+ * функционала ветвления процесса в API операционной системы.
+ *
+ * Ветвление не оказывает влияния на состояние MDBX-среды в родительском
+ * процессе. Все транзакции, которые были в родительском процессе на момент
+ * ветвления, после ветвления в родительском процессе продолжат выполняться без
+ * помех. Но в дочернем процессе все соответствующие транзакции безальтернативно
+ * перестают быть валидными, а попытка их использования приведет к возврату
+ * ошибки или отправке `SIGSEGV`.
+ *
+ * Использование экземпляра среды в дочернем процессе не возможно до вызова
+ * \ref mdbx_env_resurrect_after_fork(), так как в результате ветвления у
+ * процесса меняется PID, значение которого используется для организации
+ * совместно работы с БД, в том числе, для отслеживания процессов/потоков
+ * выполняющих читающие транзакции связанные с соответствующими снимками данных.
+ * Все активные на момент ветвления транзакции не могут продолжаться в дочернем
+ * процессе, так как не владеют какими-либо блокировками или каким-либо снимком
+ * данных и не удерживает его от переработки при сборке мусора.
+ *
+ * Функция \ref mdbx_env_resurrect_after_fork() восстанавливает переданный
+ * экземпляр среды в дочернем процессе после ветвления, а именно: обновляет
+ * используемые системные идентификаторы, повторно открывает дескрипторы файлов,
+ * производит захват необходимых блокировок связанных с LCK- и DXB-файлами БД,
+ * восстанавливает отображения в память страницы БД, таблицы читателей и
+ * служебных/вспомогательных данных в память. Однако унаследованные от
+ * родительского процесса транзакции не восстанавливаются, прием пишущие и
+ * читающие транзакции обрабатываются по-разному:
+ *
+ *  - Пишущая транзакция, если таковая была на момент ветвления,
+ *    прерывается в дочернем процессе с освобождение связанных с ней ресурсов,
+ *    включая все вложенные транзакции.
+ *
+ *  - Читающие же транзакции, если таковые были в родительском процессе,
+ *    в дочернем процессе логически прерываются, но без освобождения ресурсов.
+ *    Поэтому необходимо обеспечить вызов \ref mdbx_txn_abort() для каждой
+ *    такой читающей транзакций в дочернем процессе, либо смириться с утечкой
+ *    ресурсов до завершения дочернего процесса.
+ *
+ * Причина не-освобождения ресурсов читающих транзакций в том, что исторически
+ * MDBX не ведет какой-либо общий список экземпляров читающих, так как это не
+ * требуется для штатных режимов работы, но требует использования атомарных
+ * операций или дополнительных объектов синхронизации при создании/разрушении
+ * экземпляров \ref MDBX_txn.
+ *
+ * Вызов \ref mdbx_env_resurrect_after_fork() без ветвления, не в дочернем
+ * процессе, либо повторные вызовы не приводят к каким-либо действиям или
+ * изменениям.
+ *
+ * \returns Ненулевое значение ошибки при сбое и 0 при успешном выполнении,
+ *          некоторые возможные ошибки таковы:
+ *
+ * \retval MDBX_BUSY      В родительском процессе БД была открыта
+ *                        в режиме \ref MDBX_EXCLUSIVE.
+ *
+ * \retval MDBX_EBADSIGN  При повреждении сигнатуры экземпляра объекта, а также
+ *                        в случае одновременного вызова \ref
+ *                        mdbx_env_resurrect_after_fork() из разных потоков.
+ *
+ * \retval MDBX_PANIC     Произошла критическая ошибка при восстановлении
+ *                        экземпляра среды, либо такая ошибка уже была
+ *                        до вызова функции. */
 LIBMDBX_API int mdbx_env_resurrect_after_fork(MDBX_env *env);
 #endif /* Windows */