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

finished documentation for Storage object, added doxygen awesome theme support

Browse Source
This commit is contained in:
Blue 2023-04-09 14:19:23 -03:00
parent 6d21ecc155
commit ec0d2d57f0
Signed by: blue
GPG Key ID: 9B203B252A63EE38
3 changed files with 157 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
CMakeLists.txt
View File

@ -9,6 +9,7 @@ cmake_policy(SET CMP0079 NEW)
option(BUILD_STATIC "Builds library as static library" OFF)
option(BUILD_TESTS "Builds tests" OFF)
option(BUILD_DOC "Builds documentation" OFF)
option(BUILD_DOXYGEN_AWESOME "Builds documentation alternative style" OFF)
include(GNUInstallDirs)
include(CMakePackageConfigHelpers)

22
doc/CMakeLists.txt
View File

@ -1,6 +1,24 @@
set(DOXYGEN_GENERATE_HTML YES)
set(DOXYGEN_GENERATE_MAN YES)
if (BUILD_DOXYGEN_AWESOME)
include(ExternalProject)
ExternalProject_Add(doxygen-awesome-css
GIT_REPOSITORY https://github.com/jothepro/doxygen-awesome-css.git
GIT_TAG "v2.2.0"
CONFIGURE_COMMAND ""
BUILD_COMMAND make
BUILD_IN_SOURCE TRUE
INSTALL_COMMAND make DESTDIR=${CMAKE_CURRENT_BINARY_DIR}/doxygen-awesome-css install
)
set (DOXYGEN_GENERATE_TREEVIEW YES)
set (DOXYGEN_DISABLE_INDEX NO)
set (DOXYGEN_FULL_SIDEBAR NO)
set (DOXYGEN_HTML_EXTRA_STYLESHEET ${CMAKE_CURRENT_BINARY_DIR}/doxygen-awesome-css/doxygen-awesome.css ${CMAKE_CURRENT_BINARY_DIR}/doxygen-awesome-css/doxygen-awesome-sidebar-only.css)
set (DOXYGEN_FULL_SIDEBAR NO)
set (DOXYGEN_HTML_COLORSTYLE "LIGHT")
endif()
doxygen_add_docs(
documentation
${PROJECT_SOURCE_DIR}/src
@ -8,3 +26,7 @@ doxygen_add_docs(
ALL
COMMENT "Generate man and html pages"
)
if (BUILD_DOXYGEN_AWESOME)
add_dependencies(documentation doxygen-awesome-css)
endif()

135
src/storage.hpp
View File

@ -396,6 +396,14 @@ bool LMDBAL::Storage<K, V>::checkRecord(const K& key, TransactionID txn) const {
return false;
}
/**
* \brief Reads whole storage into a map
*
* Basically just reads all database in an std::map, usefull when you store small storages
*
* \exception LMDBAL::Closed thrown if the database was not opened
* \exception LMDBAL::Unknown thrown if something unexpected happend within lmdb
*/
template<class K, class V>
std::map<K, V> LMDBAL::Storage<K, V>::readAll() const {
ensureOpened(readAllMethodName);
@ -405,6 +413,16 @@ std::map<K, V> LMDBAL::Storage<K, V>::readAll() const {
return result;
}
/**
* \brief Reads whole storage into a map (reference variant)
*
* Basically just reads all database in an std::map, usefull when you store small storages
*
* \param[out] result a map that is going to contain all data
*
* \exception LMDBAL::Closed thrown if the database was not opened
* \exception LMDBAL::Unknown thrown if something unexpected happend within lmdb
*/
template<class K, class V>
void LMDBAL::Storage<K, V>::readAll(std::map<K, V>& result) const {
ensureOpened(readAllMethodName);
@ -420,6 +438,18 @@ void LMDBAL::Storage<K, V>::readAll(std::map<K, V>& result) const {
abortTransaction(txn);
}
/**
* \brief Reads whole storage into a map (transaction variant)
*
* Basically just reads all database in an std::map, usefull when you store small storages
* You can obtain LMDBAL::TransactionID calling LMDBAL::Base::beginReadOnlyTransaction() or LMDBAL::Base::beginTransaction().
* If you just want to read data you should prefer LMDBAL::Base::beginReadOnlyTransaction().
*
* \param[in] txn transaction ID, can be read only transaction
*
* \exception LMDBAL::Closed thrown if the database was not opened
* \exception LMDBAL::Unknown thrown if something unexpected happend within lmdb
*/
template<class K, class V>
std::map<K, V> LMDBAL::Storage<K, V>::readAll(TransactionID txn) const {
ensureOpened(readAllMethodName);
@ -429,6 +459,19 @@ std::map<K, V> LMDBAL::Storage<K, V>::readAll(TransactionID txn) const {
return result;
}
/**
* \brief Reads whole storage into a map (transaction, reference variant)
*
* Basically just reads all database in an std::map, usefull when you store small storages
* You can obtain LMDBAL::TransactionID calling LMDBAL::Base::beginReadOnlyTransaction() or LMDBAL::Base::beginTransaction().
* If you just want to read data you should prefer LMDBAL::Base::beginReadOnlyTransaction().
*
* \param[out] result a map that is going to contain all data
* \param[in] txn transaction ID, can be read only transaction
*
* \exception LMDBAL::Closed thrown if the database was not opened
* \exception LMDBAL::Unknown thrown if something unexpected happend within lmdb
*/
template<class K, class V>
void LMDBAL::Storage<K, V>::readAll(std::map<K, V>& result, TransactionID txn) const {
ensureOpened(readAllMethodName);
@ -453,6 +496,16 @@ void LMDBAL::Storage<K, V>::readAll(std::map<K, V>& result, TransactionID txn) c
throwUnknown(rc);
}
/**
* \brief Replaces the content of the whole storage with the given
*
* Basically this function drops the database and adds all the records from the given map
*
* \param[in] data new data of the storage
*
* \exception LMDBAL::Closed thrown if the database was not opened
* \exception LMDBAL::Unknown thrown if something unexpected happend within lmdb
*/
template<class K, class V>
void LMDBAL::Storage<K, V>::replaceAll(const std::map<K, V>& data) {
ensureOpened(replaceAllMethodName);
@ -468,6 +521,19 @@ void LMDBAL::Storage<K, V>::replaceAll(const std::map<K, V>& data) {
commitTransaction(txn);
}
/**
* \brief Replaces the content of the whole storage with the given (transaction variant)
*
* Basically this function drops the database and adds all the records from the given map
* This function schedules a data replacement, but doesn't immidiately execute it.
* You can obtain LMDBAL::TransactionID calling LMDBAL::Base::beginTransaction().
*
* \param[in] data new data of the storage
* \param[in] txn transaction ID, needs to be a writable transaction!
*
* \exception LMDBAL::Closed thrown if the database was not opened
* \exception LMDBAL::Unknown thrown if something unexpected happend within lmdb
*/
template<class K, class V>
void LMDBAL::Storage<K, V>::replaceAll(const std::map<K, V>& data, TransactionID txn) {
ensureOpened(replaceAllMethodName);
@ -481,12 +547,23 @@ void LMDBAL::Storage<K, V>::replaceAll(const std::map<K, V>& data, TransactionID
lmdbKey = keySerializer->setData(pair.first);
lmdbData = valueSerializer->setData(pair.second);
rc = mdb_put(txn, dbi, &lmdbKey, &lmdbData, MDB_NOOVERWRITE);
rc = mdb_put(txn, dbi, &lmdbKey, &lmdbData, MDB_NOOVERWRITE); //TODO may be appending with cursor makes sence here?
if (rc != MDB_SUCCESS)
throwUnknown(rc);
}
}
/**
* \brief Adds records in bulk
*
* \param[in] data the data to be added
* \param[in] overwrite if false function throws LMDBAL::Exist on repeated key, if true - overwrites it
* \returns new actual amount of records in the storage
*
* \exception LMDBAL::Closed thrown if the database was not opened
* \exception LMDBAL::Exist thrown if overwrite==false and at least one of the keys of data already exists in the storage
* \exception LMDBAL::Unknown thrown if something unexpected happend within lmdb
*/
template<class K, class V>
uint32_t LMDBAL::Storage<K, V>::addRecords(const std::map<K, V>& data, bool overwrite) {
ensureOpened(addRecordsMethodName);
@ -504,6 +581,21 @@ uint32_t LMDBAL::Storage<K, V>::addRecords(const std::map<K, V>& data, bool over
return amount;
}
/**
* \brief Adds records in bulk (transaction variant)
*
* This function schedules a data addition, but doesn't immidiately execute it.
* You can obtain LMDBAL::TransactionID calling LMDBAL::Base::beginTransaction().
*
* \param[in] data the data to be added
* \param[in] txn transaction ID, needs to be a writable transaction!
* \param[in] overwrite if false function throws LMDBAL::Exist on repeated key, if true - overwrites it
* \returns new actual amount of records in the storage
*
* \exception LMDBAL::Closed thrown if the database was not opened
* \exception LMDBAL::Exist thrown if overwrite==false and at least one of the keys of data already exists in the storage
* \exception LMDBAL::Unknown thrown if something unexpected happend within lmdb
*/
template<class K, class V>
uint32_t LMDBAL::Storage<K, V>::addRecords(const std::map<K, V>& data, TransactionID txn, bool overwrite) {
ensureOpened(addRecordsMethodName);
@ -530,6 +622,17 @@ uint32_t LMDBAL::Storage<K, V>::addRecords(const std::map<K, V>& data, Transacti
return stat.ms_entries;
}
/**
* \brief Removes one of the records
*
* Take a note that if the storage didn't have a record you want to remove LMDBAL::NotFound is thrown
*
* \param[in] key key of the record you wish to be removed
*
* \exception LMDBAL::Closed thrown if the database was not opened
* \exception LMDBAL::NotFound thrown if the record with given key wasn't found
* \exception LMDBAL::Unknown thrown if something unexpected happend within lmdb
*/
template<class K, class V>
void LMDBAL::Storage<K, V>::removeRecord(const K& key) {
ensureOpened(removeRecordMethodName);
@ -545,6 +648,20 @@ void LMDBAL::Storage<K, V>::removeRecord(const K& key) {
commitTransaction(txn);
}
/**
* \brief Removes one of the records (transaction variant)
*
* Take a note that if the storage didn't have a record you want to remove LMDBAL::NotFound is thrown
* This function schedules a record removal, but doesn't immidiately execute it.
* You can obtain LMDBAL::TransactionID calling LMDBAL::Base::beginTransaction().
*
* \param[in] key key of the record you wish to be removed
* \param[in] txn transaction ID, needs to be a writable transaction!
*
* \exception LMDBAL::Closed thrown if the database was not opened
* \exception LMDBAL::NotFound thrown if the record with given key wasn't found
* \exception LMDBAL::Unknown thrown if something unexpected happend within lmdb
*/
template<class K, class V>
void LMDBAL::Storage<K, V>::removeRecord(const K& key, TransactionID txn) {
ensureOpened(removeRecordMethodName);
@ -555,6 +672,13 @@ void LMDBAL::Storage<K, V>::removeRecord(const K& key, TransactionID txn) {
throwNotFoundOrUnknown(rc, toString(key));
}
/**
* \brief A private virtual function I need to open 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
*/
template<class K, class V>
int LMDBAL::Storage<K, V>::createStorage(MDB_txn* transaction) {
return makeTable<K>(transaction);
@ -605,6 +729,15 @@ inline int LMDBAL::iStorage::makeTable<int8_t>(MDB_txn* transaction) {
return mdb_dbi_open(transaction, name.c_str(), MDB_CREATE | MDB_INTEGERKEY, &dbi);
}
/**
* \brief A method to cast a value (which can be a value or a key) to string.
*
* This function is mainly used in exceptions, to report which key was duplicated or not found.
* You can define your own specializations to this function in case std::to_string doesn't cover your case
*
* \param[in] value a value that should be converted to string
* \returns a string presentation of value
*/
template<class T>
inline std::string LMDBAL::iStorage::toString(const T& value) {
return std::to_string(value);