blue/lmdbal
1
0
Fork 1
Code Issues 1 Pull requests Projects Releases 9 Packages Wiki Activity Actions

Base class documentation, doxugen tweaking, new exception for one case

Browse source
This commit is contained in:
Blue 2023-04-10 18:01:19 -03:00
parent ec0d2d57f0
commit af0e48a684
Signed by: blue
GPG key ID: 9B203B252A63EE38
11 changed files with 408 additions and 20 deletions
Download patch file Download diff file Expand all files Collapse all files

206
src/base.cpp
View file

@ -22,6 +22,20 @@
#define UNUSED(x) (void)(x)
/**
* \class LMDBAL::Base
* \brief Database abstraction
*
* This is a basic class that represents the database as a collection of storages.
* Storages is something key-value database has instead of tables in classic SQL databases.
*/
/**
* \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 <a class="el" href="http://www.lmdb.tech/doc/group__mdb.html#gaa2506ec8dab3d969b0e609cd82e619e5">mdb_env_set_mapsize</a> during the call of LMDBAL::Base::open()
*/
LMDBAL::Base::Base(const QString& p_name, uint16_t mapSize):
name(p_name.toStdString()),
opened(false),
@ -31,6 +45,9 @@ LMDBAL::Base::Base(const QString& p_name, uint16_t mapSize):
transactions(new Transactions())
{}
/**
* \brief Destroys the database
*/
LMDBAL::Base::~Base() {
close();
@ -40,6 +57,14 @@ LMDBAL::Base::~Base() {
delete pair.second;
}
/**
* \brief Closes the database
*
* Closes all lmdb handles, aborts all public transactions.
* This function will do nothing on closed database
*
* \exception LMDBAL::Unknown - thrown if something went wrong aborting transactions
*/
void LMDBAL::Base::close() {
if (opened) {
for (LMDBAL::TransactionID id : *transactions)
@ -56,7 +81,13 @@ void LMDBAL::Base::close() {
}
/**
* Almost every LMDBAL::Base require it to be opened, this function opens it. It laso creates the directory for the database if it was an initial launch
* \brief Opens the database
*
* Almost every LMDBAL::Base require it to be opened, this function does it.
* It laso creates the directory for the database if it was an initial launch.
* This function will do nothing on opened database
*
* \exception LMDBAL::Unknown - thrown if something went wrong opening storages and caches
*/
void LMDBAL::Base::open() {
if (!opened) {
@ -79,6 +110,13 @@ void LMDBAL::Base::open() {
}
}
/**
* \brief Removes database directory
*
* \returns true if removal was successfull of if no directory was created where it's expected to be, false otherwise
*
* \exception LMDBAL::Opened - thrown if this function was called on opened database
*/
bool LMDBAL::Base::removeDirectory() {
if (opened)
throw Opened(name, "remove database directory");
@ -93,6 +131,20 @@ bool LMDBAL::Base::removeDirectory() {
return true;
}
/**
* \brief Creates database directory
*
* Creates or opens existing directory with the given name in the location acquired with
* <a class="el" href="https://doc.qt.io/qt-6/qstandardpaths.html">QStandardPaths</a>::<a class="el" href="https://doc.qt.io/qt-6/qstandardpaths.html#writableLocation">writableLocation</a>(<a class="el" href="https://doc.qt.io/qt-6/qstandardpaths.html">QStandardPaths</a>::<a class="el" href="https://doc.qt.io/qt-6/qstandardpaths.html#StandardLocation-enum">CacheLocation</a>)
* so, the file system destination of your data would depend on the
* <a class="el" href="https://doc.qt.io/qt-6/qcoreapplication.html">QCoreApplication</a> configuration of your app.
* This function does nothing if the directory was already created
*
* \returns the path of the created directory
*
* \exception LMDBAL::Opened - thrown if called on opened database
* \exception LMDBAL::Directory - if the database couldn't create the folder
*/
QString LMDBAL::Base::createDirectory() {
if (opened)
throw Opened(name, "create database directory");
@ -110,12 +162,31 @@ QString LMDBAL::Base::createDirectory() {
return path;
}
/**
* \brief Returns database name
*
* \returns database name
*/
QString LMDBAL::Base::getName() const {
return QString::fromStdString(name);}
/**
* \brief Returns database state
*
* \returns true if the database is opened and ready for work, false otherwise
*/
bool LMDBAL::Base::ready() const {
return opened;}
/**
* \brief Drops the database
*
* Clears all caches and storages of the database
*
* \exception LMDBAL::Closed - thrown if the database is closed
* \exception LMDBAL::Unknown - thrown if something unexpected happend
*/
void LMDBAL::Base::drop() {
if (!opened)
throw Closed("drop", name);
@ -131,18 +202,67 @@ void LMDBAL::Base::drop() {
commitTransaction(txn);
}
/**
* \brief Begins read-only transaction
*
* \returns read-only transaction ID
*
* \exception LMDBAL::Closed - thrown if the database is closed
* \exception LMDBAL::Unknown - thrown if something unexpected happened
*/
LMDBAL::TransactionID LMDBAL::Base::beginReadOnlyTransaction() const {
return beginReadOnlyTransaction(emptyName);}
/**
* \brief Begins writable transaction
*
* \returns writable transaction ID
*
* \exception LMDBAL::Closed - thrown if the database is closed
* \exception LMDBAL::Unknown - thrown if something unexpected happened
*/
LMDBAL::TransactionID LMDBAL::Base::beginTransaction() const {
return beginTransaction(emptyName);}
/**
* \brief Aborts transaction
*
* Terminates transaction cancelling changes.
* This is an optimal way to terminate read-only transactions
*
* \param[in] id - transaction ID you want to abort
*
* \exception LMDBAL::Closed - thrown if the database is closed
* \exception LMDBAL::Unknown - thrown if transaction with given ID was not found or if something unexpected happened
*/
void LMDBAL::Base::abortTransaction(LMDBAL::TransactionID id) const {
return abortTransaction(id, emptyName);}
/**
* \brief Commits transaction
*
* Terminates transaction applying changes.
*
* \param[in] id - transaction ID you want to commit
*
* \exception LMDBAL::Closed - thrown if the database is closed
* \exception LMDBAL::Unknown - thrown if transaction with given ID was not found or if something unexpected happened
*/
void LMDBAL::Base::commitTransaction(LMDBAL::TransactionID id) {
return commitTransaction(id, emptyName);}
/**
* \brief Begins read-only transaction
*
* This function is intended to be called from subordinate storage or cache
*
* \param[in] storageName - name of the storage/cache that you begin transaction from, needed just to inform if something went wrong
*
* \returns read-only transaction ID
*
* \exception LMDBAL::Closed - thrown if the database is closed
* \exception LMDBAL::Unknown - thrown if something unexpected happened
*/
LMDBAL::TransactionID LMDBAL::Base::beginReadOnlyTransaction(const std::string& storageName) const {
if (!opened)
throw Closed("beginReadOnlyTransaction", name, storageName);
@ -155,6 +275,18 @@ LMDBAL::TransactionID LMDBAL::Base::beginReadOnlyTransaction(const std::string&
return txn;
}
/**
* \brief Begins writable transaction
*
* This function is intended to be called from subordinate storage or cache
*
* \param[in] storageName - name of the storage/cache that you begin transaction from, needed just to inform if something went wrong
*
* \returns writable transaction ID
*
* \exception LMDBAL::Closed - thrown if the database is closed
* \exception LMDBAL::Unknown - thrown if something unexpected happened
*/
LMDBAL::TransactionID LMDBAL::Base::beginTransaction(const std::string& storageName) const {
if (!opened)
throw Closed("beginTransaction", name, storageName);
@ -167,6 +299,19 @@ LMDBAL::TransactionID LMDBAL::Base::beginTransaction(const std::string& storageN
return txn;
}
/**
* \brief Aborts transaction
*
* Terminates transaction cancelling changes.
* This is an optimal way to terminate read-only transactions.
* This function is intended to be called from subordinate storage or cache
*
* \param[in] id - transaction ID you want to abort
* \param[in] storageName - name of the storage/cache that you begin transaction from, needed just to inform if something went wrong
*
* \exception LMDBAL::Closed - thrown if the database is closed
* \exception LMDBAL::Unknown - thrown if transaction with given ID was not found or if something unexpected happened
*/
void LMDBAL::Base::abortTransaction(LMDBAL::TransactionID id, const std::string& storageName) const {
if (!opened)
throw Closed("abortTransaction", name, storageName);
@ -182,6 +327,18 @@ void LMDBAL::Base::abortTransaction(LMDBAL::TransactionID id, const std::string&
transactions->erase(itr);
}
/**
* \brief Commits transaction
*
* Terminates transaction applying changes.
* This function is intended to be called from subordinate storage or cache
*
* \param[in] id - transaction ID you want to commit
* \param[in] storageName - name of the storage/cache that you begin transaction from, needed just to inform if something went wrong
*
* \exception LMDBAL::Closed - thrown if the database is closed
* \exception LMDBAL::Unknown - thrown if transaction with given ID was not found or if something unexpected happened
*/
void LMDBAL::Base::commitTransaction(LMDBAL::TransactionID id, const std::string& storageName) {
if (!opened)
throw Closed("abortTransaction", name, storageName);
@ -197,6 +354,18 @@ void LMDBAL::Base::commitTransaction(LMDBAL::TransactionID id, const std::string
transactions->erase(itr);
}
/**
* \brief Begins read-only transaction
*
* This function is intended to be called from subordinate storage or cache,
* it's not accounted in transaction collection, other storages and caches are not notified about this kind of transaction
*
* \param[in] storageName - name of the storage/cache that you begin transaction from, needed just to inform if something went wrong
*
* \returns read-only transaction ID
*
* \exception LMDBAL::Unknown - thrown if something unexpected happened
*/
LMDBAL::TransactionID LMDBAL::Base::beginPrivateReadOnlyTransaction(const std::string& storageName) const {
MDB_txn* txn;
int rc = mdb_txn_begin(environment, NULL, MDB_RDONLY, &txn);
@ -207,6 +376,18 @@ LMDBAL::TransactionID LMDBAL::Base::beginPrivateReadOnlyTransaction(const std::s
return txn;
}
/**
* \brief Begins writable transaction
*
* This function is intended to be called from subordinate storage or cache,
* it's not accounted in transaction collection, other storages and caches are not notified about this kind of transaction
*
* \param[in] storageName - name of the storage/cache that you begin transaction from, needed just to inform if something went wrong
*
* \returns writable transaction ID
*
* \exception LMDBAL::Unknown - thrown if something unexpected happened
*/
LMDBAL::TransactionID LMDBAL::Base::beginPrivateTransaction(const std::string& storageName) const {
MDB_txn* txn;
int rc = mdb_txn_begin(environment, NULL, 0, &txn);
@ -217,11 +398,34 @@ LMDBAL::TransactionID LMDBAL::Base::beginPrivateTransaction(const std::string& s
return txn;
}
/**
* \brief Aborts transaction
*
* Terminates transaction cancelling changes.
* This is an optimal way to terminate read-only transactions.
* This function is intended to be called from subordinate storage or cache,
* it's not accounted in transaction collection, other storages and caches are not notified about this kind of transaction
*
* \param[in] id - transaction ID you want to abort
* \param[in] storageName - name of the storage/cache that you begin transaction from, unused here
*/
void LMDBAL::Base::abortPrivateTransaction(LMDBAL::TransactionID id, const std::string& storageName) const {
UNUSED(storageName);
mdb_txn_abort(id);
}
/**
* \brief Commits transaction
*
* Terminates transaction applying changes.
* This function is intended to be called from subordinate storage or cache
* it's not accounted in transaction collection, other storages and caches are not notified about this kind of transaction
*
* \param[in] id - transaction ID you want to commit
* \param[in] storageName - name of the storage/cache that you begin transaction from, needed just to inform if something went wrong
*
* \exception LMDBAL::Unknown - thrown if transaction with given ID was not found or if something unexpected happened
*/
void LMDBAL::Base::commitPrivateTransaction(LMDBAL::TransactionID id, const std::string& storageName) {
int rc = mdb_txn_commit(id);
if (rc != MDB_SUCCESS)

70
src/base.h
View file

@ -109,7 +109,19 @@ private:
#include "operators.hpp"
/**
* Adds LMDBAL::Storage with the given name to the LMDBAL::Base, also returns it. The LMDBAL::Base must be closed
* \brief Adds LMDBAL::Storage to the database
*
* Defines that the database is going to have the following storage.
* The LMDBAL::Base must be closed
*
* \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
* \tparam V - value type of the storage
*
* \exception LMDBAL::Opened thrown if this method is called on the opened database
* \exception LMDBAL::StorageDuplicate thrown if somebody tries to add storage with repeating name
*/
template <class K, class V>
LMDBAL::Storage<K, V>* LMDBAL::Base::addStorage(const std::string& p_name) {
@ -117,12 +129,27 @@ LMDBAL::Storage<K, V>* LMDBAL::Base::addStorage(const std::string& p_name) {
throw Opened(name, "add storage " + p_name);
}
Storage<K, V>* storage = new Storage<K, V>(p_name, this);
storages.insert(std::make_pair(p_name, (iStorage*)storage));
std::pair<Storages::const_iterator, bool> pair = storages.insert(std::make_pair(p_name, (iStorage*)storage));
if (!pair.second)
throw StorageDuplicate(name, p_name);
return storage;
}
/**
* Adds LMDBAL::Cache with given the name to the LMDBAL::Base, also returns it. The LMDBAL::Base must be closed
* \brief Adds LMDBAL::Cache to the database
*
* Defines that the database is going to have the following cache.
* The LMDBAL::Base must be closed
*
* \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
* \tparam V - value type of the cahce
*
* \exception LMDBAL::Opened thrown if this method is called on the opened database
* \exception LMDBAL::StorageDuplicate thrown if somebody tries to add cache with repeating name
*/
template<class K, class V>
LMDBAL::Cache<K, V> * LMDBAL::Base::addCache(const std::string& p_name) {
@ -130,12 +157,29 @@ LMDBAL::Cache<K, V> * LMDBAL::Base::addCache(const std::string& p_name) {
throw Opened(name, "add cache " + p_name);
}
Cache<K, V>* cache = new Cache<K, V>(p_name, this);
storages.insert(std::make_pair(p_name, (iStorage*)cache));
std::pair<Storages::const_iterator, bool> pair = storages.insert(std::make_pair(p_name, (iStorage*)cache));
if (!pair.second)
throw StorageDuplicate(name, p_name);
return cache;
}
/**
* Returns LMDBAL::Storage with the given name
* \brief Returns LMDBAL::Storage handle
*
* Requested storage must have been added before opening database
* Note that template parameters is user responsibility zone!
* If user, for instance, had added storage <int, int> but calling
* this method with template parameters <std::string, std::string>
* on the same name of the previously added storage, or calling it on cache - the behaviour is undefined
*
* \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
* \tparam V - value type of the storage
*
* \exception std::out_of_range thrown if storage with the given name was not found
*/
template <class K, class V>
LMDBAL::Storage<K, V>* LMDBAL::Base::getStorage(const std::string& p_name) {
@ -143,7 +187,21 @@ LMDBAL::Storage<K, V>* LMDBAL::Base::getStorage(const std::string& p_name) {
}
/**
* Returns LMDBAL::Cache with the given name
* \brief Returns LMDBAL::Cache handle
*
* Requested cache must have been added before opening database
* Note that template parameters is user responsibility zone!
* If user, for instance, had added cache <int, int> but calling
* this method with template parameters <std::string, std::string>
* on the same name of the previously added cache, or calling it on storage - the behaviour is undefined
*
* \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
* \tparam V - value type of the cahce
*
* \exception std::out_of_range thrown if cache with the given name was not found
*/
template <class K, class V>
LMDBAL::Cache<K, V>* LMDBAL::Base::getCache(const std::string& p_name) {

14
src/exceptions.cpp
View file

@ -82,6 +82,20 @@ std::string LMDBAL::NotFound::getMessage() const {
+ " in database " + dbName
+ " in table " + tableName;}
LMDBAL::StorageDuplicate::StorageDuplicate(
const std::string& p_dbName,
const std::string& p_tableName
):
dbName(p_dbName),
tableName(p_tableName) {}
std::string LMDBAL::StorageDuplicate::getMessage() const {
return "An attempt to add a storage (or cache) " + tableName
+ " to database " + dbName
+ " but the database already has a storage with given name";
}
LMDBAL::Exist::Exist(
const std::string& p_key,
const std::string& p_dbName,

10
src/exceptions.h
View file

@ -76,6 +76,16 @@ private:
std::string tableName;
};
class StorageDuplicate : public Exception {
public:
StorageDuplicate(const std::string& dbName, const std::string& tableName);
std::string getMessage() const;
private:
std::string dbName;
std::string tableName;
};
class Exist : public Exception {
public:
Exist(const std::string& key, const std::string& dbName, const std::string& tableName);

2
src/storage.h
View file

@ -83,7 +83,7 @@ protected:
protected:
template <class T>
int makeTable(MDB_txn* transaction);
int makeStorage(MDB_txn* transaction);
template <class T>
static std::string toString(const T& value);

20
src/storage.hpp
View file

@ -681,51 +681,51 @@ void LMDBAL::Storage<K, V>::removeRecord(const K& key, TransactionID txn) {
*/
template<class K, class V>
int LMDBAL::Storage<K, V>::createStorage(MDB_txn* transaction) {
return makeTable<K>(transaction);
return makeStorage<K>(transaction);
}
template<class K>
inline int LMDBAL::iStorage::makeTable(MDB_txn* transaction) {
inline int LMDBAL::iStorage::makeStorage(MDB_txn* transaction) {
return mdb_dbi_open(transaction, name.c_str(), MDB_CREATE, &dbi);
}
template<>
inline int LMDBAL::iStorage::makeTable<uint64_t>(MDB_txn* transaction) {
inline int LMDBAL::iStorage::makeStorage<uint64_t>(MDB_txn* transaction) {
return mdb_dbi_open(transaction, name.c_str(), MDB_CREATE | MDB_INTEGERKEY, &dbi);
}
template<>
inline int LMDBAL::iStorage::makeTable<uint32_t>(MDB_txn* transaction) {
inline int LMDBAL::iStorage::makeStorage<uint32_t>(MDB_txn* transaction) {
return mdb_dbi_open(transaction, name.c_str(), MDB_CREATE | MDB_INTEGERKEY, &dbi);
}
template<>
inline int LMDBAL::iStorage::makeTable<uint16_t>(MDB_txn* transaction) {
inline int LMDBAL::iStorage::makeStorage<uint16_t>(MDB_txn* transaction) {
return mdb_dbi_open(transaction, name.c_str(), MDB_CREATE | MDB_INTEGERKEY, &dbi);
}
template<>
inline int LMDBAL::iStorage::makeTable<uint8_t>(MDB_txn* transaction) {
inline int LMDBAL::iStorage::makeStorage<uint8_t>(MDB_txn* transaction) {
return mdb_dbi_open(transaction, name.c_str(), MDB_CREATE | MDB_INTEGERKEY, &dbi);
}
template<>
inline int LMDBAL::iStorage::makeTable<int64_t>(MDB_txn* transaction) {
inline int LMDBAL::iStorage::makeStorage<int64_t>(MDB_txn* transaction) {
return mdb_dbi_open(transaction, name.c_str(), MDB_CREATE | MDB_INTEGERKEY, &dbi);
}
template<>
inline int LMDBAL::iStorage::makeTable<int32_t>(MDB_txn* transaction) {
inline int LMDBAL::iStorage::makeStorage<int32_t>(MDB_txn* transaction) {
return mdb_dbi_open(transaction, name.c_str(), MDB_CREATE | MDB_INTEGERKEY, &dbi);
}
template<>
inline int LMDBAL::iStorage::makeTable<int16_t>(MDB_txn* transaction) {
inline int LMDBAL::iStorage::makeStorage<int16_t>(MDB_txn* transaction) {
return mdb_dbi_open(transaction, name.c_str(), MDB_CREATE | MDB_INTEGERKEY, &dbi);
}
template<>
inline int LMDBAL::iStorage::makeTable<int8_t>(MDB_txn* transaction) {
inline int LMDBAL::iStorage::makeStorage<int8_t>(MDB_txn* transaction) {
return mdb_dbi_open(transaction, name.c_str(), MDB_CREATE | MDB_INTEGERKEY, &dbi);
}