forked from blue/lmdbal
462 lines
17 KiB
C++
462 lines
17 KiB
C++
/*
|
|
* LMDB Abstraction Layer.
|
|
* Copyright (C) 2023 Yury Gubich <blue@macaw.me>
|
|
*
|
|
* This program is free software: you can redistribute it and/or modify
|
|
* it under the terms of the GNU General Public License as published by
|
|
* the Free Software Foundation, either version 3 of the License, or
|
|
* (at your option) any later version.
|
|
*
|
|
* This program is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License
|
|
* along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
*/
|
|
|
|
#include "base.h"
|
|
#include "exceptions.h"
|
|
#include "storage.h"
|
|
#include "transaction.h"
|
|
|
|
#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 (MiB), 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& _name, uint16_t _mapSize):
|
|
name(_name.toStdString()),
|
|
opened(false),
|
|
size(_mapSize),
|
|
environment(),
|
|
storages(),
|
|
transactions()
|
|
{}
|
|
|
|
/**
|
|
* \brief Destroys the database
|
|
*/
|
|
LMDBAL::Base::~Base() {
|
|
close();
|
|
|
|
for (const std::pair<const std::string, StorageCommon*>& pair : storages)
|
|
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 (const std::pair<LMDBAL::TransactionID, LMDBAL::Transaction*> pair : transactions) {
|
|
abortTransaction(pair.first, emptyName);
|
|
pair.second->reset();
|
|
}
|
|
|
|
for (const std::pair<const std::string, StorageCommon*>& pair : storages)
|
|
pair.second->close();
|
|
|
|
mdb_env_close(environment);
|
|
transactions.clear();
|
|
opened = false;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* \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) {
|
|
mdb_env_create(&environment);
|
|
QString path = createDirectory();
|
|
|
|
mdb_env_set_maxdbs(environment, storages.size());
|
|
mdb_env_set_mapsize(environment, size * 1024UL * 1024UL);
|
|
mdb_env_open(environment, path.toStdString().c_str(), 0, 0664);
|
|
|
|
TransactionID txn = beginPrivateTransaction(emptyName);
|
|
for (const std::pair<const std::string, StorageCommon*>& pair : storages) {
|
|
StorageCommon* storage = pair.second;
|
|
int rc = storage->open(txn);
|
|
if (rc)
|
|
throw Unknown(name, mdb_strerror(rc));
|
|
}
|
|
commitPrivateTransaction(txn, emptyName);
|
|
opened = true;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* \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");
|
|
|
|
QString path = getPath();
|
|
QDir cache(path);
|
|
|
|
if (cache.exists())
|
|
return cache.removeRecursively();
|
|
else
|
|
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");
|
|
|
|
QString path = getPath();
|
|
QDir cache(path);
|
|
if (!cache.exists()) {
|
|
bool res = cache.mkpath(path);
|
|
if (!res)
|
|
throw Directory(path.toStdString());
|
|
}
|
|
|
|
return path;
|
|
}
|
|
|
|
/**
|
|
* \brief Returns database name
|
|
*
|
|
* \returns database name
|
|
*/
|
|
QString LMDBAL::Base::getName() const {
|
|
return QString::fromStdString(name);}
|
|
|
|
/**
|
|
* \brief Returns database name
|
|
*
|
|
* \returns database path
|
|
*/
|
|
QString LMDBAL::Base::getPath() const {
|
|
QString path(QStandardPaths::writableLocation(QStandardPaths::CacheLocation));
|
|
path += "/" + getName();
|
|
|
|
return path;
|
|
}
|
|
|
|
/**
|
|
* \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);
|
|
|
|
TransactionID txn = beginPrivateTransaction(emptyName);
|
|
for (const std::pair<const std::string, StorageCommon*>& pair : storages) {
|
|
int rc = pair.second->drop(txn);
|
|
if (rc != MDB_SUCCESS) {
|
|
abortPrivateTransaction(txn, emptyName);
|
|
throw Unknown(name, mdb_strerror(rc), pair.first);
|
|
}
|
|
}
|
|
|
|
commitPrivateTransaction(txn, emptyName);
|
|
for (const std::pair<const std::string, StorageCommon*>& pair : storages)
|
|
pair.second->handleDrop();
|
|
}
|
|
|
|
/**
|
|
* \brief Begins read-only transaction
|
|
*
|
|
* This is the legitimate way to retrieve LMDBAL::Transaction.
|
|
* LMDBAL::Transaction is considered runnig right after creation by this method.
|
|
* You can terminate transaction manually calling LMDBAL::Transaction::terminate
|
|
* but it's not required, because transaction will be terminated automatically
|
|
* (if it was not terminated manually) upon the call of the destructor.
|
|
*
|
|
* You can not use termitated transaction any more.
|
|
*
|
|
* \returns read-only transaction
|
|
*
|
|
* \exception LMDBAL::Closed - thrown if the database is closed
|
|
* \exception LMDBAL::Unknown - thrown if something unexpected happened
|
|
*/
|
|
LMDBAL::Transaction LMDBAL::Base::beginReadOnlyTransaction() const {
|
|
TransactionID id = beginReadOnlyTransaction(emptyName);
|
|
return Transaction(id, this);
|
|
}
|
|
|
|
/**
|
|
* \brief Begins writable transaction
|
|
*
|
|
* This is the legitimate way to retrieve LMDBAL::WriteTransaction.
|
|
* LMDBAL::WriteTransaction is considered runnig right after creation by this method.
|
|
* You can commit all the changes made by this transaction calling LMDBAL::WriteTransaction::commit.
|
|
* You can cancel any changes made bu this transaction calling LMDBAL::WriteTransaction::abort
|
|
* (or LMDBAL::Transaction::terminate which LMDBAL::WriteTransaction inherits),
|
|
* but it's not required, because transaction will be aborted automatically
|
|
* (if it was not terminated (committed <b>OR</b> aborted) manually) upon the call of the destructor.
|
|
*
|
|
* You can not use termitated transaction any more.
|
|
*
|
|
* \returns writable transaction
|
|
*
|
|
* \exception LMDBAL::Closed - thrown if the database is closed
|
|
* \exception LMDBAL::Unknown - thrown if something unexpected happened
|
|
*/
|
|
LMDBAL::WriteTransaction LMDBAL::Base::beginTransaction() {
|
|
TransactionID id = beginTransaction(emptyName);
|
|
return WriteTransaction(id, this);
|
|
}
|
|
|
|
/**
|
|
* \brief Aborts transaction
|
|
*
|
|
* Terminates transaction cancelling changes.
|
|
* Every storage receives notification about this transaction being aborted.
|
|
* This is an optimal way to abort public transactions
|
|
*
|
|
* \param[in] id - transaction ID you want to abort
|
|
*
|
|
* \exception LMDBAL::Closed - thrown if the database is closed
|
|
* \exception LMDBAL::Unknown - thrown if something unexpected happened
|
|
*/
|
|
void LMDBAL::Base::abortTransaction(LMDBAL::TransactionID id) const {
|
|
return abortTransaction(id, emptyName);}
|
|
|
|
/**
|
|
* \brief Commits transaction
|
|
*
|
|
* Terminates transaction applying changes.
|
|
* Every storage receives notification about this transaction being committed.
|
|
* This is an optimal way to commit public transactions
|
|
*
|
|
* \param[in] id - transaction ID you want to commit
|
|
*
|
|
* \exception LMDBAL::Closed - thrown if the database is closed
|
|
* \exception LMDBAL::Unknown - thrown 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, cache, transaction or cursor.
|
|
* Every storage receives notification about this transaction being started.
|
|
* This is an optimal way to begin read-only public transactions.
|
|
*
|
|
* \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);
|
|
|
|
TransactionID txn = beginPrivateReadOnlyTransaction(storageName);
|
|
for (const std::pair<const std::string, LMDBAL::StorageCommon*>& pair : storages)
|
|
pair.second->transactionStarted(txn, true);
|
|
|
|
return txn;
|
|
}
|
|
|
|
/**
|
|
* \brief Begins writable transaction
|
|
*
|
|
* This function is intended to be called from subordinate storage, cache, transaction or cursor.
|
|
* Every storage receives notification about this transaction being started.
|
|
* This is an optimal way to begin public transactions.
|
|
*
|
|
* \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);
|
|
|
|
TransactionID txn = beginPrivateTransaction(storageName);
|
|
for (const std::pair<const std::string, LMDBAL::StorageCommon*>& pair : storages)
|
|
pair.second->transactionStarted(txn, false);
|
|
|
|
return txn;
|
|
}
|
|
|
|
/**
|
|
* \brief Aborts transaction
|
|
*
|
|
* Terminates transaction cancelling changes.
|
|
* Every storage receives notification about this transaction being aborted.
|
|
* This is an optimal way to abort public transactions.
|
|
* This function is intended to be called from subordinate storage, cache, transaction or cursor
|
|
*
|
|
* \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 something unexpected happened
|
|
*/
|
|
void LMDBAL::Base::abortTransaction(LMDBAL::TransactionID id, const std::string& storageName) const {
|
|
if (!opened)
|
|
throw Closed("abortTransaction", name, storageName);
|
|
|
|
abortPrivateTransaction(id, storageName);
|
|
for (const std::pair<const std::string, LMDBAL::StorageCommon*>& pair : storages)
|
|
pair.second->transactionAborted(id);
|
|
}
|
|
|
|
/**
|
|
* \brief Commits transaction
|
|
*
|
|
* Terminates transaction applying changes.
|
|
* Every storage receives notification about this transaction being committed.
|
|
* This is an optimal way to commit public transactions
|
|
* This function is intended to be called from subordinate storage, cache, transaction or cursor
|
|
*
|
|
* \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 something unexpected happened
|
|
*/
|
|
void LMDBAL::Base::commitTransaction(LMDBAL::TransactionID id, const std::string& storageName) {
|
|
if (!opened)
|
|
throw Closed("abortTransaction", name, storageName);
|
|
|
|
commitPrivateTransaction(id, storageName);
|
|
for (const std::pair<const std::string, LMDBAL::StorageCommon*>& pair : storages)
|
|
pair.second->transactionCommited(id);
|
|
}
|
|
|
|
/**
|
|
* \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);
|
|
if (rc != MDB_SUCCESS)
|
|
throw Unknown(name, mdb_strerror(rc), storageName);
|
|
|
|
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);
|
|
if (rc != MDB_SUCCESS) {
|
|
mdb_txn_abort(txn);
|
|
throw Unknown(name, mdb_strerror(rc), storageName);
|
|
}
|
|
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)
|
|
throw Unknown(name, mdb_strerror(rc), storageName);
|
|
}
|