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)