ISAR/libmdbx
3
0
Fork 0
mirror of https://github.com/isar/libmdbx.git synced 2025-01-30 16:32:06 +08:00
Code Issues Packages Projects Releases Wiki Activity

mdbx: refine MDBX_opt_* descriptions and defaults.

Browse Source 
Change-Id: I99ddf530d5683b755bc8bab1ea1098b0cc00b181
This commit is contained in:
Leonid Yuriev 2020-12-08 00:01:29 +03:00
parent 697fce7ebc
commit 082df3a573
2 changed files with 96 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

112
mdbx.h
View File

@ -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,
MDBX_opt_sync_period,
MDBX_opt_max_dbx,
/** \brief Controls the maximum number of named databases for the environment.
*
* \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. */
MDBX_opt_dp_reserve_limit,
/** \brief Controls interprocess/shared threshold to force flush the data
* 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
* for finding a sequence of contiguous pages. */
/** \brief Controls interprocess/shared relative period since the last
* 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.
* \ingroup c_settings
/** \brief Set the maximum number of threads/reader slots for for all processes
* interacts with the database. \ingroup c_settings
*
* This defines the number of slots in the lock table that is used to track
* readers in the the environment. The default is 119 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
* \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 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;

6
src/core.c
View File

@ -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;