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

mdbx: refine Doxygen's API description.

Browse Source 
Change-Id: Ifd326eded287c68c6a95b6c9be22847d6efa5678
This commit is contained in:
Leonid Yuriev 2021-05-03 14:19:34 +03:00
parent 65919abd9a
commit c914d417d2
4 changed files with 81 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.github/actions/spelling/expect.txt vendored
View File

@ -1315,6 +1315,7 @@ putc
putchar
putflags
pv
pvalue
PVOID
PWIM
PWIN

78
mdbx.h
View File

@ -1957,11 +1957,32 @@ enum MDBX_option_t {
typedef enum MDBX_option_t MDBX_option_t;
#endif
/** \brief Sets the value of a runtime options for an environment.
* \ingroup c_settings
*
* \param [in] env An environment handle returned by \ref mdbx_env_create().
* \param [in] option The option from \ref MDBX_option_t to set value of it.
* \param [in] value The value of option to be set.
*
* \see MDBX_option_t
* \see mdbx_env_get_option()
* \returns A non-zero error value on failure and 0 on success. */
LIBMDBX_API int mdbx_env_set_option(MDBX_env *env, const MDBX_option_t option,
const uint64_t value);
/** \brief Gets the value of runtime options from an environment.
* \ingroup c_settings
*
* \param [in] env An environment handle returned by \ref mdbx_env_create().
* \param [in] option The option from \ref MDBX_option_t to get value of it.
* \param [out] pvalue The address where the option's value will be stored.
*
* \see MDBX_option_t
* \see mdbx_env_get_option()
* \returns A non-zero error value on failure and 0 on success. */
LIBMDBX_API int mdbx_env_get_option(const MDBX_env *env,
const MDBX_option_t option,
uint64_t *value);
uint64_t *pvalue);
/** \brief Open an environment instance.
* \ingroup c_opening
@ -2876,12 +2897,23 @@ LIBMDBX_INLINE_API(int, mdbx_env_get_maxdbs,
MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API size_t mdbx_default_pagesize(void);
/** \brief Returns basic information about system RAM.
* This function provides a portable way to get information about available RAM
* and can be useful in that it returns the same information that libmdbx uses
* internally to adjust various options and control readahead.
* \ingroup c_statinfo
*/
*
* \param [out] page_size Optional address where the system page size
* will be stored.
* \param [out] total_pages Optional address where the number of total RAM
* pages will be stored.
* \param [out] avail_pages Optional address where the number of
* available/free RAM pages will be stored.
*
* \returns A non-zero error value on failure and 0 on success. */
LIBMDBX_API int mdbx_get_sysraminfo(intptr_t *page_size, intptr_t *total_pages,
intptr_t *avail_pages);
/** \brief Get the maximum size of keys can write.
/** \brief Returns the maximum size of keys can put.
* \ingroup c_statinfo
*
* \param [in] env An environment handle returned by \ref mdbx_env_create().
@ -2893,7 +2925,7 @@ LIBMDBX_API int mdbx_get_sysraminfo(intptr_t *page_size, intptr_t *total_pages,
MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int
mdbx_env_get_maxkeysize_ex(const MDBX_env *env, MDBX_db_flags_t flags);
/** \brief Get the maximum size of data we can write.
/** \brief Returns the maximum size of data we can put.
* \ingroup c_statinfo
*
* \param [in] env An environment handle returned by \ref mdbx_env_create().
@ -2911,9 +2943,10 @@ mdbx_env_get_maxvalsize_ex(const MDBX_env *env, MDBX_db_flags_t flags);
MDBX_NOTHROW_PURE_FUNCTION MDBX_DEPRECATED LIBMDBX_API int
mdbx_env_get_maxkeysize(const MDBX_env *env);
/** \brief Set application information associated with the \ref MDBX_env.
* \ingroup c_settings
/** \brief Sets application information (a context pointer) associated with
* the environment.
* \see mdbx_env_get_userctx()
* \ingroup c_settings
*
* \param [in] env An environment handle returned by \ref mdbx_env_create().
* \param [in] ctx An arbitrary pointer for whatever the application needs.
@ -2921,9 +2954,10 @@ mdbx_env_get_maxkeysize(const MDBX_env *env);
* \returns A non-zero error value on failure and 0 on success. */
LIBMDBX_API int mdbx_env_set_userctx(MDBX_env *env, void *ctx);
/** \brief Get the application information associated with the MDBX_env.
* \ingroup c_statinfo
/** \brief Returns an application information (a context pointer) associated
* with the environment.
* \see mdbx_env_set_userctx()
* \ingroup c_statinfo
*
* \param [in] env An environment handle returned by \ref mdbx_env_create()
* \returns The pointer set by \ref mdbx_env_set_userctx()
@ -2969,7 +3003,8 @@ mdbx_env_get_userctx(const MDBX_env *env);
* to \ref MDBX_NOMETASYNC or \ref MDBX_SAFE_NOSYNC
* description. \see sync_modes
*
* \param [out] txn Address where the new MDBX_txn handle will be stored.
* \param [out] txn Address where the new \ref MDBX_txn handle
* will be stored.
*
* \param [in] context A pointer to application context to be associated with
* created transaction and could be retrieved by
@ -3030,7 +3065,8 @@ LIBMDBX_API int mdbx_txn_begin_ex(MDBX_env *env, MDBX_txn *parent,
* to \ref MDBX_NOMETASYNC or \ref MDBX_SAFE_NOSYNC
* description. \see sync_modes
*
* \param [out] txn Address where the new MDBX_txn handle will be stored.
* \param [out] txn Address where the new \ref MDBX_txn handle
* will be stored.
*
* \returns A non-zero error value on failure and 0 on success,
* some possible errors are:
@ -3052,7 +3088,8 @@ LIBMDBX_INLINE_API(int, mdbx_txn_begin,
return mdbx_txn_begin_ex(env, parent, flags, txn, NULL);
}
/** \brief Set application information associated with the \ref MDBX_txn.
/** \brief Sets application information associated (a context pointer) with the
* transaction.
* \ingroup c_transactions
* \see mdbx_txn_get_userctx()
*
@ -3063,7 +3100,8 @@ LIBMDBX_INLINE_API(int, mdbx_txn_begin,
* \returns A non-zero error value on failure and 0 on success. */
LIBMDBX_API int mdbx_txn_set_userctx(MDBX_txn *txn, void *ctx);
/** \brief Get the application information associated with the MDBX_txn.
/** \brief Returns an application information (a context pointer) associated
* with the transaction.
* \ingroup c_transactions
* \see mdbx_txn_set_userctx()
*
@ -3286,8 +3324,8 @@ LIBMDBX_API int mdbx_txn_abort(MDBX_txn *txn);
/** \brief Marks transaction as broken.
* \ingroup c_transactions
*
* Function keeps the transaction handle and corresponding locks, but it
* is not possible to perform any operations in a broken transaction.
* Function keeps the transaction handle and corresponding locks, but makes
* impossible to perform any operations within a broken transaction.
* Broken transaction must then be aborted explicitly later.
*
* \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
@ -4131,7 +4169,7 @@ LIBMDBX_API MDBX_dbi mdbx_cursor_dbi(const MDBX_cursor *cursor);
LIBMDBX_API int mdbx_cursor_copy(const MDBX_cursor *src, MDBX_cursor *dest);
/** \brief Retrieve by cursor.
* \ingroup c_cursors c_crud
* \ingroup c_crud
*
* This function retrieves key/data pairs from the database. The address and
* length of the key are returned in the object to which key refers (except
@ -4155,7 +4193,7 @@ LIBMDBX_API int mdbx_cursor_get(MDBX_cursor *cursor, MDBX_val *key,
MDBX_val *data, MDBX_cursor_op op);
/** \brief Store by cursor.
* \ingroup c_cursors c_crud
* \ingroup c_crud
*
* This function stores key/data pairs into the database. The cursor is
* positioned at the new item, or on failure usually near it.
@ -4238,7 +4276,7 @@ LIBMDBX_API int mdbx_cursor_put(MDBX_cursor *cursor, const MDBX_val *key,
MDBX_val *data, MDBX_put_flags_t flags);
/** \brief Delete current key/data pair.
* \ingroup c_cursors c_crud
* \ingroup c_crud
*
* This function deletes the key/data pair to which the cursor refers. This
* does not invalidate the cursor, so operations such as \ref MDBX_NEXT can
@ -4270,7 +4308,7 @@ LIBMDBX_API int mdbx_cursor_put(MDBX_cursor *cursor, const MDBX_val *key,
LIBMDBX_API int mdbx_cursor_del(MDBX_cursor *cursor, MDBX_put_flags_t flags);
/** \brief Return count of duplicates for current key.
* \ingroup c_cursors c_crud
* \ingroup c_crud
*
* This call is valid for all databases, but reasonable only for that support
* sorted duplicate data items \ref MDBX_DUPSORT.
@ -4809,8 +4847,8 @@ LIBMDBX_API int mdbx_env_turn_for_recovery(MDBX_env *env, unsigned target_meta);
/** @} B-tree Traversal */
/**** Attribute support functions for Nexenta
* *******************************************/
/**** Attribute support functions for Nexenta (scheduled for removal)
* *****************************************************************/
#if defined(MDBX_NEXENTA_ATTRS) || defined(DOXYGEN)
/** \defgroup nexenta Attribute support functions for Nexenta
* \ingroup c_crud

10
mdbx.h++
View File

@ -1814,8 +1814,11 @@ public:
env::operate_options options;
MDBX_CXX11_CONSTEXPR operate_parameters() noexcept {}
MDBX_env_flags_t make_flags(bool accede = true, ///< \copydoc MDBX_ACCEDE
bool use_subdirectory = false) const;
MDBX_env_flags_t
make_flags(bool accede = true, ///< \copydoc MDBX_ACCEDE
bool use_subdirectory =
false ///< use subdirectory to place the DB files
) const;
static env::mode mode_from_flags(MDBX_env_flags_t) noexcept;
static env::durability durability_from_flags(MDBX_env_flags_t) noexcept;
inline static env::reclaiming_options
@ -2491,6 +2494,9 @@ public:
/// increase in the length of the value will be twice as slow, since it will
/// require splitting already filled pages.
///
/// \param [in] map A map handle to append
/// \param [in] key A key to be append
/// \param [in] value A value to store with the key
/// \param [in] multivalue_order_preserved
/// If `multivalue_order_preserved == true` then the same rules applied for
/// to pages of nested b+tree of multimap's values.

28
src/core.c
View File

@ -21691,63 +21691,63 @@ __cold int mdbx_env_set_option(MDBX_env *env, const MDBX_option_t option,
}
__cold int mdbx_env_get_option(const MDBX_env *env, const MDBX_option_t option,
uint64_t *value) {
uint64_t *pvalue) {
int err = check_env(env, false);
if (unlikely(err != MDBX_SUCCESS))
return err;
if (unlikely(!value))
if (unlikely(!pvalue))
return MDBX_EINVAL;
switch (option) {
case MDBX_opt_sync_bytes:
if (unlikely(!(env->me_flags & MDBX_ENV_ACTIVE)))
return MDBX_EPERM;
*value = pgno2bytes(
*pvalue = pgno2bytes(
env, atomic_load32(&env->me_lck->mti_autosync_threshold, mo_Relaxed));
break;
case MDBX_opt_sync_period:
if (unlikely(!(env->me_flags & MDBX_ENV_ACTIVE)))
return MDBX_EPERM;
*value = mdbx_osal_monotime_to_16dot16(
*pvalue = mdbx_osal_monotime_to_16dot16(
atomic_load64(&env->me_lck->mti_autosync_period, mo_Relaxed));
break;
case MDBX_opt_max_db:
*value = env->me_maxdbs - CORE_DBS;
*pvalue = env->me_maxdbs - CORE_DBS;
break;
case MDBX_opt_max_readers:
*value = env->me_maxreaders;
*pvalue = env->me_maxreaders;
break;
case MDBX_opt_dp_reserve_limit:
*value = env->me_options.dp_reserve_limit;
*pvalue = env->me_options.dp_reserve_limit;
break;
case MDBX_opt_rp_augment_limit:
*value = env->me_options.rp_augment_limit;
*pvalue = env->me_options.rp_augment_limit;
break;
case MDBX_opt_txn_dp_limit:
*value = env->me_options.dp_limit;
*pvalue = env->me_options.dp_limit;
break;
case MDBX_opt_txn_dp_initial:
*value = env->me_options.dp_initial;
*pvalue = env->me_options.dp_initial;
break;
case MDBX_opt_spill_max_denominator:
*value = env->me_options.spill_max_denominator;
*pvalue = env->me_options.spill_max_denominator;
break;
case MDBX_opt_spill_min_denominator:
*value = env->me_options.spill_min_denominator;
*pvalue = env->me_options.spill_min_denominator;
break;
case MDBX_opt_spill_parent4child_denominator:
*value = env->me_options.spill_parent4child_denominator;
*pvalue = env->me_options.spill_parent4child_denominator;
break;
case MDBX_opt_loose_limit:
*value = env->me_options.dp_loose_limit;
*pvalue = env->me_options.dp_loose_limit;
break;
default: