diff --git a/README.md b/README.md
index fa4de83..7880758 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,7 @@
[](https://git.macaw.me/blue/lmdbal/raw/branch/master/LICENSE.md)
[](https://aur.archlinux.org/packages/lmdbal/)
[](https://liberapay.com/macaw.me)
+[](https://macaw.me/lmdbal/doc/html)
### Prerequisites
diff --git a/src/base.cpp b/src/base.cpp
index 8952652..01cd3c1 100644
--- a/src/base.cpp
+++ b/src/base.cpp
@@ -33,13 +33,13 @@
/**
* \brief Creates the database
*
- * \param[in] name - name of the database, it is going to affect folder name that is created to store data
- * \param[in] mapSize - LMDB map size (MBi), multiplied by 1024^2 and passed to mdb_env_set_mapsize during the call of LMDBAL::Base::open()
+ * \param[in] _name - name of the database, it is going to affect folder name that is created to store data
+ * \param[in] _mapSize - LMDB map size (MBi), multiplied by 1024^2 and passed to mdb_env_set_mapsize during the call of LMDBAL::Base::open()
*/
-LMDBAL::Base::Base(const QString& p_name, uint16_t mapSize):
- name(p_name.toStdString()),
+LMDBAL::Base::Base(const QString& _name, uint16_t _mapSize):
+ name(_name.toStdString()),
opened(false),
- size(mapSize),
+ size(_mapSize),
environment(),
storages(),
transactions(new Transactions())
diff --git a/src/base.h b/src/base.h
index 1168b3b..e02d06f 100644
--- a/src/base.h
+++ b/src/base.h
@@ -114,7 +114,7 @@ private:
* Defines that the database is going to have the following storage.
* The LMDBAL::Base must be closed
*
- * \param[in] name - storage name
+ * \param[in] _name - storage name
* \returns storage pointer. LMDBAL::Base keeps the ownership of the added storage, you don't need to destoroy it
*
* \tparam K - key type of the storage
@@ -124,14 +124,14 @@ private:
* \exception LMDBAL::StorageDuplicate thrown if somebody tries to add storage with repeating name
*/
template
-LMDBAL::Storage* LMDBAL::Base::addStorage(const std::string& p_name) {
+LMDBAL::Storage* LMDBAL::Base::addStorage(const std::string& _name) {
if (opened) {
- throw Opened(name, "add storage " + p_name);
+ throw Opened(name, "add storage " + _name);
}
- Storage* storage = new Storage(p_name, this);
- std::pair pair = storages.insert(std::make_pair(p_name, (iStorage*)storage));
+ Storage* storage = new Storage(_name, this);
+ std::pair pair = storages.insert(std::make_pair(_name, (iStorage*)storage));
if (!pair.second)
- throw StorageDuplicate(name, p_name);
+ throw StorageDuplicate(name, _name);
return storage;
}
@@ -142,7 +142,7 @@ LMDBAL::Storage* LMDBAL::Base::addStorage(const std::string& p_name) {
* Defines that the database is going to have the following cache.
* The LMDBAL::Base must be closed
*
- * \param[in] name - cache name
+ * \param[in] _name - cache name
* \returns cache pointer. LMDBAL::Base keeps the ownership of the added cache, you don't need to destoroy it
*
* \tparam K - key type of the cache
@@ -152,14 +152,14 @@ LMDBAL::Storage* LMDBAL::Base::addStorage(const std::string& p_name) {
* \exception LMDBAL::StorageDuplicate thrown if somebody tries to add cache with repeating name
*/
template
-LMDBAL::Cache * LMDBAL::Base::addCache(const std::string& p_name) {
+LMDBAL::Cache * LMDBAL::Base::addCache(const std::string& _name) {
if (opened) {
- throw Opened(name, "add cache " + p_name);
+ throw Opened(name, "add cache " + _name);
}
- Cache* cache = new Cache(p_name, this);
- std::pair pair = storages.insert(std::make_pair(p_name, (iStorage*)cache));
+ Cache* cache = new Cache(_name, this);
+ std::pair pair = storages.insert(std::make_pair(_name, (iStorage*)cache));
if (!pair.second)
- throw StorageDuplicate(name, p_name);
+ throw StorageDuplicate(name, _name);
return cache;
}
@@ -173,7 +173,7 @@ LMDBAL::Cache * LMDBAL::Base::addCache(const std::string& p_name) {
* this method with template parameters
* on the same name of the previously added storage, or calling it on cache - the behaviour is undefined
*
- * \param[in] name - storage name
+ * \param[in] _name - storage name
* \returns storage pointer. LMDBAL::Base keeps the ownership of the added storage, you don't need to destoroy it
*
* \tparam K - key type of the storage
@@ -182,8 +182,8 @@ LMDBAL::Cache * LMDBAL::Base::addCache(const std::string& p_name) {
* \exception std::out_of_range thrown if storage with the given name was not found
*/
template
-LMDBAL::Storage* LMDBAL::Base::getStorage(const std::string& p_name) {
- return static_cast*>(storages.at(p_name));
+LMDBAL::Storage* LMDBAL::Base::getStorage(const std::string& _name) {
+ return static_cast*>(storages.at(_name));
}
/**
@@ -195,7 +195,7 @@ LMDBAL::Storage* LMDBAL::Base::getStorage(const std::string& p_name) {
* this method with template parameters
* on the same name of the previously added cache, or calling it on storage - the behaviour is undefined
*
- * \param[in] name - cache name
+ * \param[in] _name - cache name
* \returns cache pointer. LMDBAL::Base keeps the ownership of the added cache, you don't need to destoroy it
*
* \tparam K - key type of the cache
@@ -204,8 +204,8 @@ LMDBAL::Storage* LMDBAL::Base::getStorage(const std::string& p_name) {
* \exception std::out_of_range thrown if cache with the given name was not found
*/
template
-LMDBAL::Cache* LMDBAL::Base::getCache(const std::string& p_name) {
- return static_cast*>(storages.at(p_name));
+LMDBAL::Cache* LMDBAL::Base::getCache(const std::string& _name) {
+ return static_cast*>(storages.at(_name));
}
#endif //LMDBAL_BASE_H
diff --git a/src/storage.cpp b/src/storage.cpp
index 351ae9d..8737b6f 100644
--- a/src/storage.cpp
+++ b/src/storage.cpp
@@ -20,14 +20,36 @@
#define UNUSED(x) (void)(x)
+/**
+ * \class LMDBAL::iStorage
+ *
+ * This is a interface-like class, it's designed to be an inner database interface to
+ * be used as a polymorphic entity, and provide protected interaction with the database
+ * from the heirs code
+ */
+
+/**
+ * \brief Constructs a storage interface
+ */
LMDBAL::iStorage::iStorage(const std::string& p_name, Base* parent):
dbi(),
db(parent),
name(p_name)
{}
+/**
+ * \brief Destroys a storage interface
+ */
LMDBAL::iStorage::~iStorage() {}
+/**
+ * \brief Drops content of a storage interface
+ *
+ * Designed to drop storage content
+ *
+ * \exception LMDBAL::Closed thrown if the database was closed
+ * \exception LMDBAL::Unknown thrown if something unexpected happened
+ */
void LMDBAL::iStorage::drop() {
ensureOpened(dropMethodName);
@@ -41,15 +63,38 @@ void LMDBAL::iStorage::drop() {
db->commitTransaction(txn);
}
+/**
+ * \brief Drops content of a storage interface (transaction variant)
+ *
+ * Just performs content drop
+ *
+ * \param[in] transaction - transaction ID, must be writable transaction!
+ * \returns MDB_SUCCESS if everything went fine, MDB_ code otherwise
+ */
int LMDBAL::iStorage::drop(TransactionID transaction) {
return mdb_drop(transaction, dbi, 0);
}
+/**
+ * \brief Helper function, thows exception if the database is not opened
+ *
+ * \param[in] methodName - name of the method this function is called from, just for display in std::exception::what() message
+ *
+ * \exception LMDBAL::Closed thrown if the database was closed
+ */
void LMDBAL::iStorage::ensureOpened(const std::string& methodName) const {
- if (!db->opened)
+ if (!isDBOpened())
throw Closed(methodName, db->name, name);
}
+/**
+ * \brief Storage size
+ *
+ * \returns amount of records in the storage
+ *
+ * \exception LMDBAL::Closed thrown if the database was closed
+ * \exception LMDBAL::Unknown thrown if something unexpected happened
+ */
LMDBAL::SizeType LMDBAL::iStorage::count() const {
ensureOpened(countMethodName);
@@ -66,6 +111,14 @@ LMDBAL::SizeType LMDBAL::iStorage::count() const {
return amount;
}
+/**
+ * \brief Storage size (transaction variant)
+ *
+ * \param[in] txn - transaction ID, can be read-only transaction
+ * \returns amount of records in the storage
+ *
+ * \exception LMDBAL::Unknown thrown if something unexpected happened
+ */
LMDBAL::SizeType LMDBAL::iStorage::count(TransactionID txn) const {
MDB_stat stat;
int rc = mdb_stat(txn, dbi, &stat);
@@ -75,16 +128,51 @@ LMDBAL::SizeType LMDBAL::iStorage::count(TransactionID txn) const {
return stat.ms_entries;
}
+/**
+ * \brief Throws LMDBAL::Exist or LMDBAL::Unknown (transaction vairiant)
+ *
+ * Helper function ment to be used in heirs and reduce the code a bit
+ *
+ * \param[in] rc - result of lmdb low level operation
+ * \param[in] txn - transaction ID to be aborted, any transaction
+ * \param[in] key - requested key string representation, just to show in std::exception::what() message
+ *
+ * \exception LMDBAL::Exist thrown if rc == MDB_KEYEXIST
+ * \exception LMDBAL::Unknown thrown if rc != MDB_KEYEXIST
+ */
void LMDBAL::iStorage::throwDuplicateOrUnknown(int rc, TransactionID txn, const std::string& key) const {
abortTransaction(txn);
throwDuplicateOrUnknown(rc, key);
}
+/**
+ * \brief Throws LMDBAL::NotFound or LMDBAL::Unknown (transaction vairiant)
+ *
+ * Helper function ment to be used in heirs and reduce the code a bit
+ *
+ * \param[in] rc - result of lmdb low level operation
+ * \param[in] txn - transaction ID to be aborted, any transaction
+ * \param[in] key - requested key string representation, just to show in std::exception::what() message
+ *
+ * \exception LMDBAL::NotFound thrown if rc == MDB_NOTFOUND
+ * \exception LMDBAL::Unknown thrown if rc != MDB_NOTFOUND
+ */
void LMDBAL::iStorage::throwNotFoundOrUnknown(int rc, LMDBAL::TransactionID txn, const std::string& key) const {
abortTransaction(txn);
throwNotFoundOrUnknown(rc, key);
}
+/**
+ * \brief Throws LMDBAL::Exist or LMDBAL::Unknown
+ *
+ * Helper function ment to be used in heirs and reduce the code a bit
+ *
+ * \param[in] rc - result of lmdb low level operation
+ * \param[in] key - requested key string representation, just to show in std::exception::what() message
+ *
+ * \exception LMDBAL::Exist thrown if rc == MDB_KEYEXIST
+ * \exception LMDBAL::Unknown thrown if rc != MDB_KEYEXIST
+ */
void LMDBAL::iStorage::throwDuplicateOrUnknown(int rc, const std::string& key) const {
if (rc == MDB_KEYEXIST)
throwDuplicate(key);
@@ -92,6 +180,17 @@ void LMDBAL::iStorage::throwDuplicateOrUnknown(int rc, const std::string& key) c
throwUnknown(rc);
}
+/**
+ * \brief Throws LMDBAL::NotFound or LMDBAL::Unknown (transaction variant)
+ *
+ * Helper function ment to be used in heirs and reduce the code a bit
+ *
+ * \param[in] rc - result of lmdb low level operation
+ * \param[in] key - requested key string representation, just to show in std::exception::what() message
+ *
+ * \exception LMDBAL::NotFound thrown if rc == MDB_NOTFOUND
+ * \exception LMDBAL::Unknown thrown if rc != MDB_NOTFOUND
+ */
void LMDBAL::iStorage::throwNotFoundOrUnknown(int rc, const std::string& key) const {
if (rc == MDB_NOTFOUND)
throwNotFound(key);
@@ -99,45 +198,157 @@ void LMDBAL::iStorage::throwNotFoundOrUnknown(int rc, const std::string& key) co
throwUnknown(rc);
}
+/**
+ * \brief Throws LMDBAL::Unknown (transaction vairiant)
+ *
+ * Helper function ment to be used in heirs and reduce the code a bit
+ *
+ * \param[in] rc - result of lmdb low level operation
+ * \param[in] txn - transaction ID to be aborted, any transaction
+ *
+ * \exception LMDBAL::Unknown thrown everytime
+ */
void LMDBAL::iStorage::throwUnknown(int rc, LMDBAL::TransactionID txn) const {
abortTransaction(txn);
throwUnknown(rc);
}
+/**
+ * \brief Database name
+ *
+ * Ment to be used in heirs, to provide some sort of interface to acces to some of the database information
+ *
+ * \returns database name
+ */
const std::string & LMDBAL::iStorage::dbName() const {
return db->name;}
+/**
+ * \brief Is database opened
+ *
+ * Ment to be used in heirs, to provide some sort of interface to acces to some of the database information
+ *
+ * \returns true if database is ipened, false otherwise
+ */
bool LMDBAL::iStorage::isDBOpened() const {
return db->opened;}
+/**
+ * \brief Throws LMDBAL::Unknown
+ *
+ * Helper function ment to be used in heirs and reduce the code a bit
+ *
+ * \param[in] rc - result of lmdb low level operation
+ *
+ * \exception LMDBAL::Unknown thrown everytime
+ */
void LMDBAL::iStorage::throwUnknown(int rc) const {
throw Unknown(db->name, mdb_strerror(rc), name);}
+/**
+ * \brief Throws LMDBAL::Exist
+ *
+ * Helper function ment to be used in heirs and reduce the code a bit
+ *
+ * \param[in] key - requested key string representation, just to show in std::exception::what() message
+ *
+ * \exception LMDBAL::Exist thrown everytime
+ */
void LMDBAL::iStorage::throwDuplicate(const std::string& key) const {
throw Exist(key, db->name, name);}
+/**
+ * \brief Throws LMDBAL::NotFound
+ *
+ * Helper function ment to be used in heirs and reduce the code a bit
+ *
+ * \param[in] key - requested key string representation, just to show in std::exception::what() message
+ *
+ * \exception LMDBAL::NotFound thrown everytime
+ */
void LMDBAL::iStorage::throwNotFound(const std::string& key) const {
throw NotFound(key, db->name, name);}
+/**
+ * \brief Begins read-only transaction
+ *
+ * Ment to be called from heirs, name is reported to the database just to be displayed in std::exception::what() message
+ *
+ * \returns read only transaction
+ */
LMDBAL::TransactionID LMDBAL::iStorage::beginReadOnlyTransaction() const {
return db->beginPrivateReadOnlyTransaction(name);}
+/**
+ * \brief Begins writable transaction
+ *
+ * Ment to be called from heirs, name is reported to the database just to be displayed in std::exception::what() message
+ *
+ * \returns read only transaction
+ */
LMDBAL::TransactionID LMDBAL::iStorage::beginTransaction() const {
return db->beginPrivateTransaction(name);}
+/**
+ * \brief Aborts transaction
+ *
+ * Ment to be called from heirs, name is reported to the database just to be displayed in std::exception::what() message
+ */
void LMDBAL::iStorage::abortTransaction(LMDBAL::TransactionID id) const {
db->abortPrivateTransaction(id, name);}
+/**
+ * \brief Commits transaction
+ *
+ * Ment to be called from heirs, name is reported to the database just to be displayed in std::exception::what() message
+ *
+ * \exception LMDBAL::Unknown thrown if something unexpected happened
+ */
void LMDBAL::iStorage::commitTransaction(LMDBAL::TransactionID id) {
db->commitPrivateTransaction(id, name);}
+/**
+ * \brief called on beginning of public transaction
+ *
+ * This function is called on every storage of the database
+ * when user calls LMDBAL::Base::beginTransaction() or LMDBAL::Base::beginReadOnlyTransaction()
+ *
+ * This function is met to be reimplemented in heirs
+ * if the heir code requires some transaction custom handling
+ *
+ * \param[in] txn - ID of started transaction
+ * \param[in] readOnly - true if transaction is read-only, false otherwise
+ */
void LMDBAL::iStorage::transactionStarted(LMDBAL::TransactionID txn, bool readOnly) const {
UNUSED(txn);
UNUSED(readOnly);
}
+
+/**
+ * \brief called on commitment of public transaction
+ *
+ * This function is called on every storage of the database
+ * when user calls LMDBAL::Base::commitTransaction(LMDBAL::TransactionID)
+ *
+ * This function is met to be reimplemented in heirs
+ * if the heir code requires some transaction custom handling
+ *
+ * \param[in] txn - ID of started transaction
+ */
void LMDBAL::iStorage::transactionCommited(LMDBAL::TransactionID txn) {
UNUSED(txn);}
+/**
+ * \brief called on abortion of public transaction
+ *
+ * This function is called on every storage of the database
+ * when user calls LMDBAL::Base::abortTransaction(LMDBAL::TransactionID)
+ *
+ * This function is met to be reimplemented in heirs
+ * if the heir code requires some transaction custom handling
+ *
+ * \param[in] txn - ID of started transaction
+ */
void LMDBAL::iStorage::transactionAborted(LMDBAL::TransactionID txn) const {
UNUSED(txn);}