From 6214423163cb5c5cc7385e9e2f6da45ea5ee61ef Mon Sep 17 00:00:00 2001 From: Hallvard Furuseth Date: Mon, 5 Aug 2013 09:55:48 +0200 Subject: [PATCH] Clarify doc: mdb_copy, nested txns, mdb_drop(). mdb_copy: Does not copy lockfile. Can trigger file growth. mdb_txn_begin(): Clarify usage restrictions. mdb_drop(): State what to do rather than what will be done, since closing the handle could otherwise be read as happening even at failure. --- libraries/liblmdb/lmdb.h | 21 ++++++++++++++------- libraries/liblmdb/mdb_copy.1 | 5 +++++ 2 files changed, 19 insertions(+), 7 deletions(-) diff --git a/libraries/liblmdb/lmdb.h b/libraries/liblmdb/lmdb.h index b3cd5ef..9e3e5b7 100644 --- a/libraries/liblmdb/lmdb.h +++ b/libraries/liblmdb/lmdb.h @@ -138,6 +138,7 @@ extern "C" { #endif +/** Unix permissions for creating files, or dummy definition for Windows */ #ifdef _MSC_VER typedef int mdb_mode_t; #else @@ -534,6 +535,10 @@ int mdb_env_open(MDB_env *env, const char *path, unsigned int flags, mdb_mode_t /** @brief Copy an MDB environment to the specified path. * * This function may be used to make a backup of an existing environment. + * No lockfile is created, since it gets recreated at need. + * @note This call can trigger significant file size growth if run in + * parallel with write transactions, because it employs a read-only + * transaction. See long-lived transactions under @ref caveats_sec. * @param[in] env An environment handle returned by #mdb_env_create(). It * must have already been opened successfully. * @param[in] path The directory in which the copy will reside. This @@ -546,6 +551,10 @@ int mdb_env_copy(MDB_env *env, const char *path); /** @brief Copy an MDB environment to the specified file descriptor. * * This function may be used to make a backup of an existing environment. + * No lockfile is created, since it gets recreated at need. + * @note This call can trigger significant file size growth if run in + * parallel with write transactions, because it employs a read-only + * transaction. See long-lived transactions under @ref caveats_sec. * @param[in] env An environment handle returned by #mdb_env_create(). It * must have already been opened successfully. * @param[in] fd The filedescriptor to write the copy to. It must @@ -718,8 +727,8 @@ int mdb_env_set_maxdbs(MDB_env *env, MDB_dbi dbs); * @param[in] parent If this parameter is non-NULL, the new transaction * will be a nested transaction, with the transaction indicated by \b parent * as its parent. Transactions may be nested to any level. A parent - * transaction may not issue any other operations besides mdb_txn_begin, - * mdb_txn_abort, or mdb_txn_commit while it has active child transactions. + * transaction and its cursors may not issue any other operations than + * mdb_txn_commit and mdb_txn_abort while it has active child transactions. * @param[in] flags Special options for this transaction. This parameter * must be set to 0 or by bitwise OR'ing together one or more of the * values described here. @@ -909,14 +918,12 @@ int mdb_dbi_flags(MDB_env *env, MDB_dbi dbi, unsigned int *flags); */ void mdb_dbi_close(MDB_env *env, MDB_dbi dbi); - /** @brief Delete a database and/or free all its pages. + /** @brief Empty or delete+close a database. * - * If the \b del parameter is 1, the DB handle will be closed - * and the DB will be deleted. * @param[in] txn A transaction handle returned by #mdb_txn_begin() * @param[in] dbi A database handle returned by #mdb_dbi_open() - * @param[in] del 1 to delete the DB from the environment, - * 0 to just free its pages. + * @param[in] del 0 to empty the DB, 1 to delete it from the + * environment and close the DB handle. * @return A non-zero error value on failure and 0 on success. */ int mdb_drop(MDB_txn *txn, MDB_dbi dbi, int del); diff --git a/libraries/liblmdb/mdb_copy.1 b/libraries/liblmdb/mdb_copy.1 index 7837de5..9b053f9 100644 --- a/libraries/liblmdb/mdb_copy.1 +++ b/libraries/liblmdb/mdb_copy.1 @@ -11,6 +11,7 @@ The .B mdb_copy utility copies an LMDB environment. The environment can be copied regardless of whether it is currently in use. +No lockfile is created, since it gets recreated at need. If .I dstpath @@ -22,6 +23,10 @@ written to stdout. Exit status is zero if no errors occur. Errors result in a non-zero exit status and a diagnostic message being written to standard error. +.SH CAVEATS +This utility can trigger significant file size growth if run +in parallel with write transactions, because pages which they +free during copying cannot be reused until the copy is done. .SH "SEE ALSO" .BR mdb_stat (1) .SH AUTHOR