mdbx: refine Doxygen's API description.

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

View File

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

78
mdbx.h
View File

@ -1957,11 +1957,32 @@ enum MDBX_option_t {
typedef enum MDBX_option_t MDBX_option_t; typedef enum MDBX_option_t MDBX_option_t;
#endif #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, LIBMDBX_API int mdbx_env_set_option(MDBX_env *env, const MDBX_option_t option,
const uint64_t value); 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, LIBMDBX_API int mdbx_env_get_option(const MDBX_env *env,
const MDBX_option_t option, const MDBX_option_t option,
uint64_t *value); uint64_t *pvalue);
/** \brief Open an environment instance. /** \brief Open an environment instance.
* \ingroup c_opening * \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); MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API size_t mdbx_default_pagesize(void);
/** \brief Returns basic information about system RAM. /** \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 * \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, LIBMDBX_API int mdbx_get_sysraminfo(intptr_t *page_size, intptr_t *total_pages,
intptr_t *avail_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 * \ingroup c_statinfo
* *
* \param [in] env An environment handle returned by \ref mdbx_env_create(). * \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_NOTHROW_PURE_FUNCTION LIBMDBX_API int
mdbx_env_get_maxkeysize_ex(const MDBX_env *env, MDBX_db_flags_t flags); 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 * \ingroup c_statinfo
* *
* \param [in] env An environment handle returned by \ref mdbx_env_create(). * \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_NOTHROW_PURE_FUNCTION MDBX_DEPRECATED LIBMDBX_API int
mdbx_env_get_maxkeysize(const MDBX_env *env); mdbx_env_get_maxkeysize(const MDBX_env *env);
/** \brief Set application information associated with the \ref MDBX_env. /** \brief Sets application information (a context pointer) associated with
* \ingroup c_settings * the environment.
* \see mdbx_env_get_userctx() * \see mdbx_env_get_userctx()
* \ingroup c_settings
* *
* \param [in] env An environment handle returned by \ref mdbx_env_create(). * \param [in] env An environment handle returned by \ref mdbx_env_create().
* \param [in] ctx An arbitrary pointer for whatever the application needs. * \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. */ * \returns A non-zero error value on failure and 0 on success. */
LIBMDBX_API int mdbx_env_set_userctx(MDBX_env *env, void *ctx); LIBMDBX_API int mdbx_env_set_userctx(MDBX_env *env, void *ctx);
/** \brief Get the application information associated with the MDBX_env. /** \brief Returns an application information (a context pointer) associated
* \ingroup c_statinfo * with the environment.
* \see mdbx_env_set_userctx() * \see mdbx_env_set_userctx()
* \ingroup c_statinfo
* *
* \param [in] env An environment handle returned by \ref mdbx_env_create() * \param [in] env An environment handle returned by \ref mdbx_env_create()
* \returns The pointer set by \ref mdbx_env_set_userctx() * \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 * to \ref MDBX_NOMETASYNC or \ref MDBX_SAFE_NOSYNC
* description. \see sync_modes * 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 * \param [in] context A pointer to application context to be associated with
* created transaction and could be retrieved by * 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 * to \ref MDBX_NOMETASYNC or \ref MDBX_SAFE_NOSYNC
* description. \see sync_modes * 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, * \returns A non-zero error value on failure and 0 on success,
* some possible errors are: * 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); 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 * \ingroup c_transactions
* \see mdbx_txn_get_userctx() * \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. */ * \returns A non-zero error value on failure and 0 on success. */
LIBMDBX_API int mdbx_txn_set_userctx(MDBX_txn *txn, void *ctx); 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 * \ingroup c_transactions
* \see mdbx_txn_set_userctx() * \see mdbx_txn_set_userctx()
* *
@ -3286,8 +3324,8 @@ LIBMDBX_API int mdbx_txn_abort(MDBX_txn *txn);
/** \brief Marks transaction as broken. /** \brief Marks transaction as broken.
* \ingroup c_transactions * \ingroup c_transactions
* *
* Function keeps the transaction handle and corresponding locks, but it * Function keeps the transaction handle and corresponding locks, but makes
* is not possible to perform any operations in a broken transaction. * impossible to perform any operations within a broken transaction.
* Broken transaction must then be aborted explicitly later. * Broken transaction must then be aborted explicitly later.
* *
* \param [in] txn A transaction handle returned by \ref mdbx_txn_begin(). * \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); LIBMDBX_API int mdbx_cursor_copy(const MDBX_cursor *src, MDBX_cursor *dest);
/** \brief Retrieve by cursor. /** \brief Retrieve by cursor.
* \ingroup c_cursors c_crud * \ingroup c_crud
* *
* This function retrieves key/data pairs from the database. The address and * 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 * 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); MDBX_val *data, MDBX_cursor_op op);
/** \brief Store by cursor. /** \brief Store by cursor.
* \ingroup c_cursors c_crud * \ingroup c_crud
* *
* This function stores key/data pairs into the database. The cursor is * This function stores key/data pairs into the database. The cursor is
* positioned at the new item, or on failure usually near it. * 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); MDBX_val *data, MDBX_put_flags_t flags);
/** \brief Delete current key/data pair. /** \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 * 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 * 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); LIBMDBX_API int mdbx_cursor_del(MDBX_cursor *cursor, MDBX_put_flags_t flags);
/** \brief Return count of duplicates for current key. /** \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 * This call is valid for all databases, but reasonable only for that support
* sorted duplicate data items \ref MDBX_DUPSORT. * 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 */ /** @} B-tree Traversal */
/**** Attribute support functions for Nexenta /**** Attribute support functions for Nexenta (scheduled for removal)
* *******************************************/ * *****************************************************************/
#if defined(MDBX_NEXENTA_ATTRS) || defined(DOXYGEN) #if defined(MDBX_NEXENTA_ATTRS) || defined(DOXYGEN)
/** \defgroup nexenta Attribute support functions for Nexenta /** \defgroup nexenta Attribute support functions for Nexenta
* \ingroup c_crud * \ingroup c_crud

View File

@ -1814,8 +1814,11 @@ public:
env::operate_options options; env::operate_options options;
MDBX_CXX11_CONSTEXPR operate_parameters() noexcept {} MDBX_CXX11_CONSTEXPR operate_parameters() noexcept {}
MDBX_env_flags_t make_flags(bool accede = true, ///< \copydoc MDBX_ACCEDE MDBX_env_flags_t
bool use_subdirectory = false) const; 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::mode mode_from_flags(MDBX_env_flags_t) noexcept;
static env::durability durability_from_flags(MDBX_env_flags_t) noexcept; static env::durability durability_from_flags(MDBX_env_flags_t) noexcept;
inline static env::reclaiming_options 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 /// increase in the length of the value will be twice as slow, since it will
/// require splitting already filled pages. /// 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 /// \param [in] multivalue_order_preserved
/// If `multivalue_order_preserved == true` then the same rules applied for /// If `multivalue_order_preserved == true` then the same rules applied for
/// to pages of nested b+tree of multimap's values. /// to pages of nested b+tree of multimap's values.

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, __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); int err = check_env(env, false);
if (unlikely(err != MDBX_SUCCESS)) if (unlikely(err != MDBX_SUCCESS))
return err; return err;
if (unlikely(!value)) if (unlikely(!pvalue))
return MDBX_EINVAL; return MDBX_EINVAL;
switch (option) { switch (option) {
case MDBX_opt_sync_bytes: case MDBX_opt_sync_bytes:
if (unlikely(!(env->me_flags & MDBX_ENV_ACTIVE))) if (unlikely(!(env->me_flags & MDBX_ENV_ACTIVE)))
return MDBX_EPERM; return MDBX_EPERM;
*value = pgno2bytes( *pvalue = pgno2bytes(
env, atomic_load32(&env->me_lck->mti_autosync_threshold, mo_Relaxed)); env, atomic_load32(&env->me_lck->mti_autosync_threshold, mo_Relaxed));
break; break;
case MDBX_opt_sync_period: case MDBX_opt_sync_period:
if (unlikely(!(env->me_flags & MDBX_ENV_ACTIVE))) if (unlikely(!(env->me_flags & MDBX_ENV_ACTIVE)))
return MDBX_EPERM; 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)); atomic_load64(&env->me_lck->mti_autosync_period, mo_Relaxed));
break; break;
case MDBX_opt_max_db: case MDBX_opt_max_db:
*value = env->me_maxdbs - CORE_DBS; *pvalue = env->me_maxdbs - CORE_DBS;
break; break;
case MDBX_opt_max_readers: case MDBX_opt_max_readers:
*value = env->me_maxreaders; *pvalue = env->me_maxreaders;
break; break;
case MDBX_opt_dp_reserve_limit: case MDBX_opt_dp_reserve_limit:
*value = env->me_options.dp_reserve_limit; *pvalue = env->me_options.dp_reserve_limit;
break; break;
case MDBX_opt_rp_augment_limit: case MDBX_opt_rp_augment_limit:
*value = env->me_options.rp_augment_limit; *pvalue = env->me_options.rp_augment_limit;
break; break;
case MDBX_opt_txn_dp_limit: case MDBX_opt_txn_dp_limit:
*value = env->me_options.dp_limit; *pvalue = env->me_options.dp_limit;
break; break;
case MDBX_opt_txn_dp_initial: case MDBX_opt_txn_dp_initial:
*value = env->me_options.dp_initial; *pvalue = env->me_options.dp_initial;
break; break;
case MDBX_opt_spill_max_denominator: case MDBX_opt_spill_max_denominator:
*value = env->me_options.spill_max_denominator; *pvalue = env->me_options.spill_max_denominator;
break; break;
case MDBX_opt_spill_min_denominator: case MDBX_opt_spill_min_denominator:
*value = env->me_options.spill_min_denominator; *pvalue = env->me_options.spill_min_denominator;
break; break;
case MDBX_opt_spill_parent4child_denominator: case MDBX_opt_spill_parent4child_denominator:
*value = env->me_options.spill_parent4child_denominator; *pvalue = env->me_options.spill_parent4child_denominator;
break; break;
case MDBX_opt_loose_limit: case MDBX_opt_loose_limit:
*value = env->me_options.dp_loose_limit; *pvalue = env->me_options.dp_loose_limit;
break; break;
default: default: