diff --git a/libraries/liblmdb/COPYRIGHT b/libraries/liblmdb/COPYRIGHT index 4482816cf5..e0eb484c7a 100644 --- a/libraries/liblmdb/COPYRIGHT +++ b/libraries/liblmdb/COPYRIGHT @@ -1,4 +1,4 @@ -Copyright 2011-2013 Howard Chu, Symas Corp. +Copyright 2011-2014 Howard Chu, Symas Corp. All rights reserved. Redistribution and use in source and binary forms, with or without diff --git a/libraries/liblmdb/lmdb.h b/libraries/liblmdb/lmdb.h index 62f0a485de..7a38a29cbb 100644 --- a/libraries/liblmdb/lmdb.h +++ b/libraries/liblmdb/lmdb.h @@ -408,7 +408,7 @@ typedef enum MDB_cursor_op { #define MDB_BAD_RSLOT (-30783) /** Transaction cannot recover - it must be aborted */ #define MDB_BAD_TXN (-30782) - /** Too big key/data, key is empty, or wrong DUPFIXED size */ + /** Unsupported size of key/DB name/data, or wrong DUPFIXED size */ #define MDB_BAD_VALSIZE (-30781) #define MDB_LAST_ERRCODE MDB_BAD_VALSIZE /** @} */ @@ -784,6 +784,10 @@ int mdb_env_get_maxreaders(MDB_env *env, unsigned int *readers); * environment. Simpler applications that use the environment as a single * unnamed database can ignore this option. * This function may only be called after #mdb_env_create() and before #mdb_env_open(). + * + * Currently a moderate number of slots are cheap but a huge number gets + * expensive: 7-120 words per transaction, and every #mdb_dbi_open() + * does a linear search of the opened slots. * @param[in] env An environment handle returned by #mdb_env_create() * @param[in] dbs The maximum number of databases * @return A non-zero error value on failure and 0 on success. Some possible @@ -951,7 +955,7 @@ int mdb_txn_renew(MDB_txn *txn); * independently of whether such a database exists. * The database handle may be discarded by calling #mdb_dbi_close(). * The old database handle is returned if the database was already open. - * The handle must only be closed once. + * The handle may only be closed once. * The database handle will be private to the current transaction until * the transaction is successfully committed. If the transaction is * aborted the handle will be closed automatically. @@ -963,7 +967,8 @@ int mdb_txn_renew(MDB_txn *txn); * use this function. * * To use named databases (with name != NULL), #mdb_env_set_maxdbs() - * must be called before opening the environment. + * must be called before opening the environment. Database names + * are kept as keys in the unnamed database. * @param[in] txn A transaction handle returned by #mdb_txn_begin() * @param[in] name The name of the database to open. If only a single * database is needed in the environment, this value may be NULL. @@ -1033,12 +1038,19 @@ int mdb_stat(MDB_txn *txn, MDB_dbi dbi, MDB_stat *stat); */ int mdb_dbi_flags(MDB_txn *txn, MDB_dbi dbi, unsigned int *flags); - /** @brief Close a database handle. + /** @brief Close a database handle. Normally unnecessary. Use with care: * * This call is not mutex protected. Handles should only be closed by * a single thread, and only if no other threads are going to reference * the database handle or one of its cursors any further. Do not close * a handle if an existing transaction has modified its database. + * Doing so can cause misbehavior from database corruption to errors + * like MDB_BAD_VALSIZE (since the DB name is gone). + * + * Closing a database handle is not necessary, but lets #mdb_dbi_open() + * reuse the handle value. Usually it's better to set a bigger + * #mdb_env_set_maxdbs(), unless that value would be large. + * * @param[in] env An environment handle returned by #mdb_env_create() * @param[in] dbi A database handle returned by #mdb_dbi_open() */ @@ -1046,6 +1058,7 @@ void mdb_dbi_close(MDB_env *env, MDB_dbi dbi); /** @brief Empty or delete+close a database. * + * See #mdb_dbi_close() for restrictions about closing the DB handle. * @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 0 to empty the DB, 1 to delete it from the @@ -1323,9 +1336,9 @@ int mdb_cursor_get(MDB_cursor *cursor, MDB_val *key, MDB_val *data, /** @brief Store by cursor. * * This function stores key/data pairs into the database. - * If the function fails for any reason, the state of the cursor will be - * unchanged. If the function succeeds and an item is inserted into the - * database, the cursor is always positioned to refer to the newly inserted item. + * The cursor is positioned at the new item, or on failure usually near it. + * @note Earlier documentation incorrectly said errors would leave the + * state of the cursor unchanged. * @param[in] cursor A cursor handle returned by #mdb_cursor_open() * @param[in] key The key operated on. * @param[in] data The data operated on. @@ -1334,7 +1347,9 @@ int mdb_cursor_get(MDB_cursor *cursor, MDB_val *key, MDB_val *data, *