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

documented iStorage, hosted docs and added readme link

This commit is contained in:
Blue 2023-04-11 12:11:27 -03:00
parent af0e48a684
commit 66df0da5f6
Signed by: blue
GPG Key ID: 9B203B252A63EE38
4 changed files with 236 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
README.md
View File

@ -3,6 +3,7 @@
[![AUR license](https://img.shields.io/aur/license/lmdbal?style=flat-square)](https://git.macaw.me/blue/lmdbal/raw/branch/master/LICENSE.md)
[![AUR version](https://img.shields.io/aur/version/lmdbal?style=flat-square)](https://aur.archlinux.org/packages/lmdbal/)
[![Liberapay patrons](https://img.shields.io/liberapay/patrons/macaw.me?logo=liberapay&style=flat-square)](https://liberapay.com/macaw.me)
[![Documentation](https://img.shields.io/badge/Documentation-HTLM-green)](https://macaw.me/lmdbal/doc/html)
### Prerequisites

10
src/base.cpp
View File

@ -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 <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()
* \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()),
LMDBAL::Base::Base(const QString& _name, uint16_t _mapSize):
name(_name.toStdString()),
opened(false),
size(mapSize),
size(_mapSize),
environment(),
storages(),
transactions(new Transactions())

36
src/base.h
View File

@ -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 <class K, class V>
LMDBAL::Storage<K, V>* LMDBAL::Base::addStorage(const std::string& p_name) {
LMDBAL::Storage<K, V>* LMDBAL::Base::addStorage(const std::string& _name) {
if (opened) {
throw Opened(name, "add storage " + p_name);
throw Opened(name, "add storage " + _name);
}
Storage<K, V>* storage = new Storage<K, V>(p_name, this);
std::pair<Storages::const_iterator, bool> pair = storages.insert(std::make_pair(p_name, (iStorage*)storage));
Storage<K, V>* storage = new Storage<K, V>(_name, this);
std::pair<Storages::const_iterator, bool> 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<K, V>* 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<K, V>* LMDBAL::Base::addStorage(const std::string& p_name) {
* \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) {
LMDBAL::Cache<K, V> * LMDBAL::Base::addCache(const std::string& _name) {
if (opened) {
throw Opened(name, "add cache " + p_name);
throw Opened(name, "add cache " + _name);
}
Cache<K, V>* cache = new Cache<K, V>(p_name, this);
std::pair<Storages::const_iterator, bool> pair = storages.insert(std::make_pair(p_name, (iStorage*)cache));
Cache<K, V>* cache = new Cache<K, V>(_name, this);
std::pair<Storages::const_iterator, bool> 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<K, V> * LMDBAL::Base::addCache(const std::string& p_name) {
* 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
* \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<K, V> * LMDBAL::Base::addCache(const std::string& p_name) {
* \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) {
return static_cast<Storage<K, V>*>(storages.at(p_name));
LMDBAL::Storage<K, V>* LMDBAL::Base::getStorage(const std::string& _name) {
return static_cast<Storage<K, V>*>(storages.at(_name));
}
/**
@ -195,7 +195,7 @@ LMDBAL::Storage<K, V>* LMDBAL::Base::getStorage(const std::string& p_name) {
* 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
* \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<K, V>* LMDBAL::Base::getStorage(const std::string& p_name) {
* \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) {
return static_cast<Cache<K, V>*>(storages.at(p_name));
LMDBAL::Cache<K, V>* LMDBAL::Base::getCache(const std::string& _name) {
return static_cast<Cache<K, V>*>(storages.at(_name));
}
#endif //LMDBAL_BASE_H

213
src/storage.cpp
View File

@ -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_<error> 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);}