From c914d417d248c96d8417935a8c2a6213465d0f96 Mon Sep 17 00:00:00 2001 From: Leonid Yuriev Date: Mon, 3 May 2021 14:19:34 +0300 Subject: [PATCH] mdbx: refine Doxygen's API description. Change-Id: Ifd326eded287c68c6a95b6c9be22847d6efa5678 --- .github/actions/spelling/expect.txt | 1 + mdbx.h | 78 +++++++++++++++++++++-------- mdbx.h++ | 10 +++- src/core.c | 28 +++++------ 4 files changed, 81 insertions(+), 36 deletions(-) diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt index 44640677..c26d3257 100644 --- a/.github/actions/spelling/expect.txt +++ b/.github/actions/spelling/expect.txt @@ -1315,6 +1315,7 @@ putc putchar putflags pv +pvalue PVOID PWIM PWIN diff --git a/mdbx.h b/mdbx.h index e002f271..3767f42b 100644 --- a/mdbx.h +++ b/mdbx.h @@ -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 diff --git a/mdbx.h++ b/mdbx.h++ index 32f9ccd3..3fc77609 100644 --- a/mdbx.h++ +++ b/mdbx.h++ @@ -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. diff --git a/src/core.c b/src/core.c index 74ba7d61..7f9b08bb 100644 --- a/src/core.c +++ b/src/core.c @@ -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: