mdbx: refine MDBX_opt_* descriptions and defaults.

Change-Id: I99ddf530d5683b755bc8bab1ea1098b0cc00b181

mdbx.h

@@ -1795,22 +1795,95 @@ LIBMDBX_API int mdbx_env_create(MDBX_env **penv);
 
 /** \brief MDBX environment options. */
 enum MDBX_option_t {
-  MDBX_opt_sync_bytes,
+  /** \brief Controls the maximum number of named databases for the environment.
-  MDBX_opt_sync_period,
+   *
-  MDBX_opt_max_dbx,
+   * \details By default only unnamed key-value database could used and
+   * appropriate value should set by `MDBX_opt_max_db` to using any more named
+   * subDB(s). To reduce overhead, use the minimum sufficient value. This option
+   * may only set after \ref mdbx_env_create() and before \ref mdbx_env_open().
+   *
+   * \see mdbx_env_set_maxdbs() \see mdbx_env_get_maxdbs() */
+  MDBX_opt_max_db,
+
+  /** \brief Defines the maximum number of threads/reader slots
+   * for all processes interacting with the database.
+   *
+   * \details This defines the number of slots in the lock table that is used to
+   * track readers in the the environment. The default is about 100 for 4K
+   * system page size. Starting a read-only transaction normally ties a lock
+   * table slot to the current thread until the environment closes or the thread
+   * exits. If \ref MDBX_NOTLS is in use, \ref mdbx_txn_begin() instead ties the
+   * slot to the \ref MDBX_txn object until it or the \ref MDBX_env object is
+   * destroyed. This option may only set after \ref mdbx_env_create() and before
+   * \ref mdbx_env_open(), and has an effect only when the database is opened by
+   * the first process interacts with the database.
+   *
+   * \see mdbx_env_set_maxreaders() \see mdbx_env_get_maxreaders() */
   MDBX_opt_max_readers,
 
-  /** \brief The limit to grow a list of pre-allocated dirty pages. */
+  /** \brief Controls interprocess/shared threshold to force flush the data
-  MDBX_opt_dp_reserve_limit,
+   * buffers to disk, if \ref MDBX_SAFE_NOSYNC is used.
+   *
+   * \see mdbx_env_set_syncbytes() \see mdbx_env_get_syncbytes() */
+  MDBX_opt_sync_bytes,
 
-  /** \brief The limit to grow a list of reclaimed pages
+  /** \brief Controls interprocess/shared relative period since the last
-   * for finding a sequence of contiguous pages. */
+   * unsteady commit to force flush the data buffers to disk,
+   * if \ref MDBX_SAFE_NOSYNC is used.
+   * \see mdbx_env_set_syncperiod() \see mdbx_env_get_syncperiod() */
+  MDBX_opt_sync_period,
+
+  /** \brief Controls the in-process limit to grow a list of reclaimed/recycled
+   * page's numbers for finding a sequence of contiguous pages for large data
+   * items.
+   *
+   * \details A long values requires allocation of contiguous database pages.
+   * To find such sequences, it may be necessary to accumulate very large lists,
+   * especially when placing very long values (more than a megabyte) in a large
+   * databases (several tens of gigabytes), which is much expensive in extreme
+   * cases. This threshold allows you to avoid such costs by allocating new
+   * pages at the end of the database (with its possible growth on disk),
+   * instead of further accumulating/reclaiming Garbage Collection records.
+   *
+   * On the other hand, too small threshold will lead to unreasonable database
+   * growth, or/and to the inability of put long values.
+   *
+   * The `MDBX_opt_rp_augment_limit` controls described limit for the current
+   * process. Default is 1048576, i.e. 2**20. This is sure enough for databases
+   * up to 4Gb with 4K page size. */
   MDBX_opt_rp_augment_limit,
 
-  /** \brief The limit of dirty pages for a write transaction. */
+  /** \brief Controls the in-process limit to grow a list of
+   * pre-allocated/reserved dirty pages.
+   *
+   * \details A 'dirty page' refers to a page that has been updated in memory
+   * only, the changes to a dirty page are not yet stored on disk.
+   * Without \ref MDBX_WRITEMAP dirty pages are allocated from memory and
+   * released when a transaction is committed. To reduce overhead, it is
+   * reasonable to release not all pages, but to leave some ones in reserve for
+   * reuse in the next transaction.
+   *
+   * The `MDBX_opt_dp_reserve_limit` allows you to set a limit for such a
+   * reserve inside the current process. Default is 1024. */
+  MDBX_opt_dp_reserve_limit,
+
+  /** \brief Controls the in-process limit of dirty pages
+   * for a write transaction.
+   *
+   * \details A 'dirty page' refers to a page that has been updated in memory
+   * only, the changes to a dirty page are not yet stored on disk.
+   * Without \ref MDBX_WRITEMAP dirty pages are allocated from memory and will
+   * be busy until are written to disk. Therefore for a large transactions is
+   * reasonable to limit dirty pages collecting above an some threshold but
+   * spill to disk instead.
+   *
+   * The `MDBX_opt_txn_dp_limit` controls described threshold for the current
+   * process. Default is 1048576, i.e. 2**20. This is sure enough for databases
+   * up to 4Gb with 4K page size. */
   MDBX_opt_txn_dp_limit,
-  /** \brief The initial allocation size for dirty pages list
+
-   * of a write transaction. */
+  /** \brief Controls the in-process initial allocation size for dirty pages
+   * list of a write transaction. Default is 1024. */
   MDBX_opt_txn_dp_initial,
 };
 #ifndef __cplusplus
@@ -2618,17 +2691,18 @@ mdbx_limits_valsize_max(intptr_t pagesize, MDBX_db_flags_t flags);
 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_API intptr_t
 mdbx_limits_txnsize_max(intptr_t pagesize);
 
-/** \brief Set the maximum number of threads/reader slots for the environment.
+/** \brief Set the maximum number of threads/reader slots for for all processes
- * \ingroup c_settings
+ * interacts with the database. \ingroup c_settings
  *
- * This defines the number of slots in the lock table that is used to track
+ * \details This defines the number of slots in the lock table that is used to
- * readers in the the environment. The default is 119 for 4K system page size.
+ * track readers in the the environment. The default is about 100 for 4K system
- * Starting a read-only transaction normally ties a lock table slot to the
+ * page size. Starting a read-only transaction normally ties a lock table slot
- * current thread until the environment closes or the thread exits. If
+ * to the current thread until the environment closes or the thread exits. If
  * \ref MDBX_NOTLS is in use, \ref mdbx_txn_begin() instead ties the slot to the
  * \ref MDBX_txn object until it or the \ref MDBX_env object is destroyed.
  * This function may only be called after \ref mdbx_env_create() and before
- * \ref mdbx_env_open().
+ * \ref mdbx_env_open(), and has an effect only when the database is opened by
+ * the first process interacts with the database.
  * \see mdbx_env_get_maxreaders()
  *
  * \param [in] env       An environment handle returned
@@ -2688,7 +2762,7 @@ LIBMDBX_INLINE_API(int, mdbx_env_get_maxreaders,
  * \retval MDBX_EINVAL   An invalid parameter was specified.
  * \retval MDBX_EPERM    The environment is already open. */
 LIBMDBX_INLINE_API(int, mdbx_env_set_maxdbs, (MDBX_env * env, MDBX_dbi dbs)) {
-  return mdbx_env_set_option(env, MDBX_opt_max_dbx, dbs);
+  return mdbx_env_set_option(env, MDBX_opt_max_db, dbs);
 }
 
 /** \brief Get the maximum number of named databases for the environment.
@@ -2706,7 +2780,7 @@ LIBMDBX_INLINE_API(int, mdbx_env_get_maxdbs,
   int rc = MDBX_EINVAL;
   if (dbs) {
     uint64_t proxy = 0;
-    rc = mdbx_env_get_option(env, MDBX_opt_max_dbx, &proxy);
+    rc = mdbx_env_get_option(env, MDBX_opt_max_db, &proxy);
     *dbs = (MDBX_dbi)proxy;
   }
   return rc;

src/core.c

@@ -9310,7 +9310,7 @@ __cold int mdbx_env_create(MDBX_env **penv) {
 
   env->me_options.dp_reserve_limit = 1024;
   env->me_options.rp_augment_limit = 1024 * 1024;
-  env->me_options.dp_limit = MDBX_PGL_LIMIT / 42;
+  env->me_options.dp_limit = 1024 * 1024;
   env->me_options.dp_initial = MDBX_PNL_INITIAL;
 
   int rc;
@@ -19756,7 +19756,7 @@ __cold int mdbx_env_set_option(MDBX_env *env, const MDBX_option_t option,
     }
     break;
 
-  case MDBX_opt_max_dbx:
+  case MDBX_opt_max_db:
     if (unlikely(value > MDBX_MAX_DBI))
       return MDBX_EINVAL;
     if (unlikely(env->me_map))
@@ -19872,7 +19872,7 @@ __cold int mdbx_env_get_option(const MDBX_env *env, const MDBX_option_t option,
     *value = mdbx_osal_monotime_to_16dot16(*env->me_autosync_period);
     break;
 
-  case MDBX_opt_max_dbx:
+  case MDBX_opt_max_db:
     *value = env->me_maxdbs - CORE_DBS;
     break;