From 2b4763b575781680a84323ef7355918660eefcc4 Mon Sep 17 00:00:00 2001 From: blue Date: Wed, 12 Apr 2023 12:36:33 -0300 Subject: [PATCH] 0.3.0 --- CMakeLists.txt | 2 +- README.md | 2 +- packaging/Archlinux/PKGBUILD | 4 +- src/base.cpp | 2 +- src/base.h | 20 +++++----- src/cache.h | 27 ++++++++----- src/cache.hpp | 27 ++++++++++++- src/storage.h | 32 ++++++++-------- src/storage.hpp | 74 ++++++++++++++++++++++++++++++++---- 9 files changed, 141 insertions(+), 49 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index c60a83e..4d719ce 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,7 +1,7 @@ cmake_minimum_required(VERSION 3.16) project(LMDBAL - VERSION 0.2.0 + VERSION 0.3.0 DESCRIPTION "LMDB (Lightning Memory-Mapped Database Manager) Abstraction Layer" LANGUAGES CXX ) diff --git a/README.md b/README.md index 7880758..9f841e6 100644 --- a/README.md +++ b/README.md @@ -3,7 +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) +[![Documentation](https://img.shields.io/badge/Documentation-HTML-green)](https://macaw.me/lmdbal/doc/html) ### Prerequisites diff --git a/packaging/Archlinux/PKGBUILD b/packaging/Archlinux/PKGBUILD index c8451c9..f5d1431 100644 --- a/packaging/Archlinux/PKGBUILD +++ b/packaging/Archlinux/PKGBUILD @@ -1,6 +1,6 @@ # Maintainer: Yury Gubich pkgname=lmdbal -pkgver=0.2.0 +pkgver=0.3.0 pkgrel=1 pkgdesc="LMDB Abstraction Layer, qt5 version" arch=('i686' 'x86_64') @@ -19,5 +19,5 @@ build() { } package() { cd "$srcdir/$pkgname" - DESTDIR="$pkgdir/" cmake --install . + cmake --install . --prefix $pkgdir/ } diff --git a/src/base.cpp b/src/base.cpp index 01cd3c1..bb34bf1 100644 --- a/src/base.cpp +++ b/src/base.cpp @@ -34,7 +34,7 @@ * \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] _mapSize - LMDB map size (MiB), multiplied by 1024^2 and passed to mdb_env_set_mapsize during the call of LMDBAL::Base::open() */ LMDBAL::Base::Base(const QString& _name, uint16_t _mapSize): name(_name.toStdString()), diff --git a/src/base.h b/src/base.h index e02d06f..3cee862 100644 --- a/src/base.h +++ b/src/base.h @@ -46,7 +46,7 @@ class Storage; template class Cache; -typedef MDB_txn* TransactionID; +typedef MDB_txn* TransactionID; /*** getCache(const std::string& name); private: - typedef std::map Storages; - typedef std::set Transactions; + typedef std::map Storages; /** Transactions; /** class Cache : public Storage { friend class Base; - enum class Mode { //it's a cache state when we: - nothing, // - know nothing about records in database on disk - size, // - know just an amount of records - full // - shure that our cache is equal to the database on disk + enum class Mode { /**& data, TransactionID txn, bool overwrite = false) override; protected: + /** + * \brief Cache mode + * + * Sometimes we have a complete information about the content of the database, + * and we don't even need to refer to lmdb to fetch or check for data. + * This member actually shows what is the current state, more about them you can read in Enum descriptions + * + * It's done with pointer to comply some of the const method limitations which would modify this state eventually + */ Mode* mode; - std::map* cache; - std::set* abscent; - SizeType* sizeDifference; - TransactionCache* transactionCache; + std::map* cache; /**<\brief Cached data*/ + std::set* abscent; /**<\brief Set of keys that are definitely not in the cache*/ + SizeType* sizeDifference; /**<\brief Difference of size between cached data and amount of records in the lmdb storage*/ + TransactionCache* transactionCache; /**<\brief All changes made under under uncommited transactions*/ }; } diff --git a/src/cache.hpp b/src/cache.hpp index 93f19dd..18d8843 100644 --- a/src/cache.hpp +++ b/src/cache.hpp @@ -22,9 +22,29 @@ #include "cache.h" #include "exceptions.h" +/** + * \class LMDBAL::Cache + * \brief Storage with additional caching in std::map + * + * \tparam K type of the keys of the cache + * \tparam V type of the values of the cache + * + * You can receive an instance of this class calling LMDBAL::Base::addCache(const std::string&) + * if the database is yet closed and you're defining the storages you're going to need. + * Or you can call LMDBAL::Base::getCache(const std::string&) if you didn't save a pointer to the cache at first + * + * You are not supposed to instantiate or destory instances of this class yourself! + */ + +/** + * \brief Creates a cache + * + * \param[in] _name - name of the new cache + * \param[in] parent - parent database pointed (borrowed) + */ template -LMDBAL::Cache::Cache(const std::string& p_name, Base* parent): - Storage(p_name, parent), +LMDBAL::Cache::Cache(const std::string& _name, Base* parent): + Storage(_name, parent), mode(new Mode), cache(new std::map()), abscent(new std::set()), @@ -35,6 +55,9 @@ LMDBAL::Cache::Cache(const std::string& p_name, Base* parent): *sizeDifference = 0; } +/** + * \brief Destroys a cache + */ template LMDBAL::Cache::~Cache() { delete transactionCache; diff --git a/src/storage.h b/src/storage.h index eb140c0..8045d25 100644 --- a/src/storage.h +++ b/src/storage.h @@ -64,22 +64,22 @@ public: virtual SizeType count(TransactionID txn) const; protected: - MDB_dbi dbi; - Base* db; - const std::string name; + MDB_dbi dbi; /**<\brief lmdb storage handle*/ + Base* db; /**<\brief parent database pointer (borrowed)*/ + const std::string name; /**<\brief this storage name*/ - inline static const std::string dropMethodName = "drop"; - inline static const std::string countMethodName = "count"; + inline static const std::string dropMethodName = "drop"; /**<\brief member function name, just for exceptions*/ + inline static const std::string countMethodName = "count"; /**<\brief member function name, just for exceptions*/ - inline static const std::string addRecordMethodName = "addRecord"; - inline static const std::string forceRecordMethodName = "forceRecord"; - inline static const std::string changeRecordMethodName = "changeRecord"; - inline static const std::string removeRecordMethodName = "removeRecord"; - inline static const std::string checkRecordMethodName = "checkRecord"; - inline static const std::string getRecordMethodName = "getRecord"; - inline static const std::string readAllMethodName = "readAllRecord"; - inline static const std::string replaceAllMethodName = "replaceAll"; - inline static const std::string addRecordsMethodName = "addRecords"; + inline static const std::string addRecordMethodName = "addRecord"; /**<\brief member function name, just for exceptions*/ + inline static const std::string forceRecordMethodName = "forceRecord"; /**<\brief member function name, just for exceptions*/ + inline static const std::string changeRecordMethodName = "changeRecord"; /**<\brief member function name, just for exceptions*/ + inline static const std::string removeRecordMethodName = "removeRecord"; /**<\brief member function name, just for exceptions*/ + inline static const std::string checkRecordMethodName = "checkRecord"; /**<\brief member function name, just for exceptions*/ + inline static const std::string getRecordMethodName = "getRecord"; /**<\brief member function name, just for exceptions*/ + inline static const std::string readAllMethodName = "readAllRecord"; /**<\brief member function name, just for exceptions*/ + inline static const std::string replaceAllMethodName = "replaceAll"; /**<\brief member function name, just for exceptions*/ + inline static const std::string addRecordsMethodName = "addRecords"; /**<\brief member function name, just for exceptions*/ protected: template @@ -122,8 +122,8 @@ public: virtual uint32_t addRecords(const std::map& data, TransactionID txn, bool overwrite = false); protected: - Serializer* keySerializer; - Serializer* valueSerializer; + Serializer* keySerializer; /**<\brief internal object that would serialize and deserialize keys*/ + Serializer* valueSerializer; /**<\brief internal object that would serialize and deserialize values*/ int createStorage(MDB_txn* transaction) override; }; diff --git a/src/storage.hpp b/src/storage.hpp index 3e9df5b..2dfdf1c 100644 --- a/src/storage.hpp +++ b/src/storage.hpp @@ -31,18 +31,27 @@ * * You can receive an instance of this class calling LMDBAL::Base::addStorage(const std::string&) * if the database is yet closed and you're defining the storages you're going to need. - * Or you can call LMDBAL::Base::getStorage(const std::string&) if the database is opened and you didn't save a pointer to the storage + * Or you can call LMDBAL::Base::getStorage(const std::string&) if you didn't save a pointer to the storage at first * * You are not supposed to instantiate or destory instances of this class yourself! */ +/** + * \brief Creates a storage + * + * \param[in] _name - name of the new storage + * \param[in] parent - parent database pointed (borrowed) + */ template -LMDBAL::Storage::Storage(const std::string& p_name, Base* parent): - iStorage(p_name, parent), +LMDBAL::Storage::Storage(const std::string& _name, Base* parent): + iStorage(_name, parent), keySerializer(new Serializer()), valueSerializer(new Serializer()) {} +/** + * \brief Destroys a storage + */ template LMDBAL::Storage::~Storage() { delete valueSerializer; @@ -673,57 +682,92 @@ void LMDBAL::Storage::removeRecord(const K& key, TransactionID txn) { } /** - * \brief A private virtual function I need to open database + * \brief A private virtual function I need to open each storage in the database * - * This and the following collection of specializations are a way to optimise database using - * MDB_INTEGERKEY flag, when the key is actually kind of an integer - * This infrastructure also allowes us to customize mdb_dbi_open call in the future + * \param[in] transaction - lmdb transaction to call mdb_dbi_open + * \returns MDB_SUCCESS if everything went smooth or MDB_ -like error code */ template int LMDBAL::Storage::createStorage(MDB_txn* transaction) { return makeStorage(transaction); } +/** + * \brief A functiion to actually open MDB_dbi storage + * + * \tparam K type of keys in opening storage + * + * \param[in] transaction - lmdb transaction to call mdb_dbi_open, must be a writable transaction! + * \returns MDB_SUCCESS if everything went smooth or MDB_ -like error code + * + * This and the following collection of specializations are a way to optimise database using + * MDB_INTEGERKEY flag, when the key is actually kind of an integer + * This infrastructure also allowes us to customize mdb_dbi_open call in the future + */ template inline int LMDBAL::iStorage::makeStorage(MDB_txn* transaction) { return mdb_dbi_open(transaction, name.c_str(), MDB_CREATE, &dbi); } +/** + * \brief Opening database function specialization for uint64_t + */ template<> inline int LMDBAL::iStorage::makeStorage(MDB_txn* transaction) { return mdb_dbi_open(transaction, name.c_str(), MDB_CREATE | MDB_INTEGERKEY, &dbi); } +/** + * \brief Opening database function specialization for uint32_t + */ template<> inline int LMDBAL::iStorage::makeStorage(MDB_txn* transaction) { return mdb_dbi_open(transaction, name.c_str(), MDB_CREATE | MDB_INTEGERKEY, &dbi); } +/** + * \brief Opening database function specialization for uint16_t + */ template<> inline int LMDBAL::iStorage::makeStorage(MDB_txn* transaction) { return mdb_dbi_open(transaction, name.c_str(), MDB_CREATE | MDB_INTEGERKEY, &dbi); } +/** + * \brief Opening database function specialization for uint8_t + */ template<> inline int LMDBAL::iStorage::makeStorage(MDB_txn* transaction) { return mdb_dbi_open(transaction, name.c_str(), MDB_CREATE | MDB_INTEGERKEY, &dbi); } +/** + * \brief Opening database function specialization for int64_t + */ template<> inline int LMDBAL::iStorage::makeStorage(MDB_txn* transaction) { return mdb_dbi_open(transaction, name.c_str(), MDB_CREATE | MDB_INTEGERKEY, &dbi); } +/** + * \brief Opening database function specialization for int32_t + */ template<> inline int LMDBAL::iStorage::makeStorage(MDB_txn* transaction) { return mdb_dbi_open(transaction, name.c_str(), MDB_CREATE | MDB_INTEGERKEY, &dbi); } +/** + * \brief Opening database function specialization for int16_t + */ template<> inline int LMDBAL::iStorage::makeStorage(MDB_txn* transaction) { return mdb_dbi_open(transaction, name.c_str(), MDB_CREATE | MDB_INTEGERKEY, &dbi); } +/** + * \brief Opening database function specialization for int8_t + */ template<> inline int LMDBAL::iStorage::makeStorage(MDB_txn* transaction) { return mdb_dbi_open(transaction, name.c_str(), MDB_CREATE | MDB_INTEGERKEY, &dbi); @@ -743,11 +787,27 @@ inline std::string LMDBAL::iStorage::toString(const T& value) { return std::to_string(value); } +/** + * \brief A method to cast a value (which can be a value or a key) to string. + * + * QString spectialization + * + * \param[in] value a value that should be converted to string + * \returns a string presentation of value + */ template<> inline std::string LMDBAL::iStorage::toString(const QString& value) { return value.toStdString(); } +/** + * \brief A method to cast a value (which can be a value or a key) to string. + * + * std::string spectialization + * + * \param[in] value a value that should be converted to string + * \returns a string presentation of value + */ template<> inline std::string LMDBAL::iStorage::toString(const std::string& value) { return value;