This is a basic key value storage. More...

#include <storage.hpp>

Inheritance diagram for LMDBAL::Storage< K, V >:

Public Member Functions
virtual void	addRecord (const K &key, const V &value)
	Adds a key-value record to the storage.

virtual void	addRecord (const K &key, const V &value, const WriteTransaction &txn)
	Adds a key-value record to the storage (public transaction variant)

virtual bool	forceRecord (const K &key, const V &value)
	Adds a key-value record to the storage, overwrites if it already exists.

virtual bool	forceRecord (const K &key, const V &value, const WriteTransaction &txn)
	Adds a key-value record to the storage, overwrites if it already exists (public transaction variant)

virtual void	changeRecord (const K &key, const V &value)
	Changes key-value record to the storage.

virtual void	changeRecord (const K &key, const V &value, const WriteTransaction &txn)
	Changes key-value record to the storage (public transaction variant)

virtual void	removeRecord (const K &key)
	Removes one of the records.

virtual void	removeRecord (const K &key, const WriteTransaction &txn)
	Removes one of the records (transaction variant)

virtual bool	checkRecord (const K &key) const
	Chechs if storage has value.

virtual bool	checkRecord (const K &key, const Transaction &txn) const
	Chechs if storage has value (public transaction variant)

virtual void	getRecord (const K &key, V &value) const
	Gets the record from the database (reference variant)

virtual void	getRecord (const K &key, V &value, const Transaction &txn) const
	Gets the record from the database (public transaction, reference variant)

virtual V	getRecord (const K &key) const
	Gets the record from the database.

virtual V	getRecord (const K &key, const Transaction &txn) const
	Gets the record from the database (public transaction variant)

virtual std::map< K, V >	readAll () const
	Reads whole storage into a map.

virtual std::map< K, V >	readAll (const Transaction &txn) const
	Reads whole storage into a map (public transaction variant)

virtual void	readAll (std::map< K, V > &result) const
	Reads whole storage into a map (reference variant)

virtual void	readAll (std::map< K, V > &result, const Transaction &txn) const
	Reads whole storage into a map (public transaction, reference variant)

virtual void	replaceAll (const std::map< K, V > &data)
	Replaces the content of the whole storage with the given.

virtual void	replaceAll (const std::map< K, V > &data, const WriteTransaction &txn)
	Replaces the content of the whole storage with the given (public transaction variant)

virtual uint32_t	addRecords (const std::map< K, V > &data, bool overwrite=false)
	Adds records in bulk.

virtual uint32_t	addRecords (const std::map< K, V > &data, const WriteTransaction &txn, bool overwrite=false)
	Adds records in bulk (public transaction variant)

Cursor< K, V >	createCursor ()
	Creates cursor.

void	destroyCursor (Cursor< K, V > &cursor)
	Frees cursor.

virtual int	drop (TransactionID transaction)
	Drops content of a storage interface (transaction variant)

virtual void	drop ()
	Drops content of a storage interface.

virtual int	drop (const WriteTransaction &txn)
	Drops content of a storage interface (public transaction variant)

Public Member Functions inherited from LMDBAL::iStorage
virtual SizeType	count () const
	Storage size.

virtual SizeType	count (const Transaction &txn) const
	Storage size (public transaction variant)

template<>
std::string	toString (const QString &value)
	A method to cast a value (which can be a value or a key) to string.

template<>
std::string	toString (const std::string &value)
	A method to cast a value (which can be a value or a key) to string.

Protected Member Functions
	Storage (Base *parent, const std::string &name, bool duplicates=false)
	Creates a storage.

	~Storage () override
	Destroys a storage.

virtual void	discoveredRecord (const K &key, const V &value) const
	A private virtual method that cursor calls when he reads a record, does nothing here but populates the LMDBAL::Cache.

virtual void	discoveredRecord (const K &key, const V &value, TransactionID txn) const
	A private virtual method that cursor calls when he reads a record, does nothing here but populates the LMDBAL::Cache.

uint32_t	flags () const
	Reads current storage flags it was opened with.

virtual void	addRecord (const K &key, const V &value, TransactionID txn)
	Adds a key-value record to the storage (private transaction variant)

virtual bool	forceRecord (const K &key, const V &value, TransactionID txn)
	Adds a key-value record to the storage, overwrites if it already exists (private transaction variant)

virtual void	changeRecord (const K &key, const V &value, TransactionID txn)
	Changes key-value record to the storage (private transaction variant)

virtual void	removeRecord (const K &key, TransactionID txn)
	Removes one of the records (private transaction variant)

virtual bool	checkRecord (const K &key, TransactionID txn) const
	Chechs if storage has value (private transaction variant)

virtual void	getRecord (const K &key, V &value, TransactionID txn) const
	Gets the record from the database (private transaction, reference variant)

virtual V	getRecord (const K &key, TransactionID txn) const
	Gets the record from the database (private transaction variant)

virtual std::map< K, V >	readAll (TransactionID txn) const
	Reads whole storage into a map (private transaction variant)

virtual void	readAll (std::map< K, V > &result, TransactionID txn) const
	Reads whole storage into a map (private transaction, reference variant)

virtual void	replaceAll (const std::map< K, V > &data, TransactionID txn)
	Replaces the content of the whole storage with the given (private transaction variant)

virtual uint32_t	addRecords (const std::map< K, V > &data, TransactionID txn, bool overwrite=false)
	Adds records in bulk (private transaction variant)

int	open (MDB_txn *transaction) override
	A private virtual method I need to open each storage in the database.

void	close () override
	A private virtual method I need to close each storage in the database.

Protected Member Functions inherited from LMDBAL::iStorage
	iStorage (Base *parent, const std::string &name, bool duplicates=false)
	Constructs a storage interface.

virtual	~iStorage ()
	Destroys a storage interface.

virtual void	handleDrop ()
	A method where database additionally handles drop.

bool	isDBOpened () const
	Is database opened.

const std::string &	dbName () const
	Database name.

void	ensureOpened (const std::string &methodName) const
	Helper function, thows exception if the database is not opened.

void	throwDuplicateOrUnknown (int rc, const std::string &key) const
	Throws LMDBAL::Exist or LMDBAL::Unknown.

void	throwDuplicateOrUnknown (int rc, TransactionID txn, const std::string &key) const
	Throws LMDBAL::Exist or LMDBAL::Unknown (transaction vairiant)

void	throwNotFoundOrUnknown (int rc, const std::string &key) const
	Throws LMDBAL::NotFound or LMDBAL::Unknown (transaction variant)

void	throwNotFoundOrUnknown (int rc, TransactionID txn, const std::string &key) const
	Throws LMDBAL::NotFound or LMDBAL::Unknown (transaction vairiant)

void	throwUnknown (int rc, TransactionID txn) const
	Throws LMDBAL::Unknown (transaction vairiant)

void	throwUnknown (int rc) const
	Throws LMDBAL::Unknown.

void	throwUnknown (const std::string &message) const
	Throws LMDBAL::Unknown.

void	throwDuplicate (const std::string &key) const
	Throws LMDBAL::Exist.

void	throwNotFound (const std::string &key) const
	Throws LMDBAL::NotFound.

void	throwCursorNotReady (const std::string &method) const
	Throws LMDBAL::CursorNotReady.

TransactionID	extractTransactionId (const Transaction &txn, const std::string &action="") const
	Checks if the transaction is still active, returns inner TransactionID.

TransactionID	beginReadOnlyTransaction () const
	Begins read-only transaction.

TransactionID	beginTransaction () const
	Begins writable transaction.

void	commitTransaction (TransactionID id)
	Commits transaction.

void	abortTransaction (TransactionID id) const
	Aborts transaction.

virtual void	transactionStarted (TransactionID txn, bool readOnly) const
	called on beginning of public transaction

virtual void	transactionCommited (TransactionID txn)
	called on commitment of public transaction

virtual void	transactionAborted (TransactionID txn) const
	called on abortion of public transaction

virtual SizeType	count (TransactionID txn) const
	Storage size (private transaction variant)

int	_mdbOpen (MDB_txn *txn, unsigned int flags=0)

int	_mdbPut (MDB_txn *txn, MDB_val &key, MDB_val &data, unsigned int flags=0)

int	_mdbGet (MDB_txn *txn, MDB_val &key, MDB_val &data) const

int	_mdbDel (MDB_txn *txn, MDB_val &key)

int	_mdbDel (MDB_txn *txn, MDB_val &key, MDB_val &data)

int	_mdbStat (MDB_txn *txn, MDB_stat &stat) const

int	_mdbFlags (MDB_txn *txn, uint32_t &flags) const

int	_mdbCursorOpen (MDB_txn txn, MDB_cursor *cursor) const

void	_mdbCursorClose (MDB_cursor *cursor) const

int	_mdbCursorGet (MDB_cursor *cursor, MDB_val &key, MDB_val &data, MDB_cursor_op operation) const

int	_mdbCursorSet (MDB_cursor *cursor, MDB_val &key) const

int	_mdbCursorDel (MDB_cursor *cursor, unsigned int flags=0)

int	_mdbCursorPut (MDB_cursor *cursor, MDB_val &key, MDB_val &data, unsigned int flags=0)

int	_mdbCursorRenew (MDB_txn txn, MDB_cursor cursor) const

MDB_txn *	_mdbCursorTxn (MDB_cursor *cursor) const

template<class K , class V >
int	makeStorage (MDB_txn *transaction, bool duplicates=false)
	A functiion to actually open MDB_dbi storage.

Protected Attributes
Serializer< K >	keySerializer
	internal object that would serialize and deserialize keys

Serializer< V >	valueSerializer
	internal object that would serialize and deserialize values

std::map< uint32_t, Cursor< K, V > * >	cursors
	a set of cursors that has been created under this storage

Protected Attributes inherited from LMDBAL::iStorage
MDB_dbi	dbi
	lmdb storage handle

Base *	db
	parent database pointer (borrowed)

const std::string	name
	this storage name

const bool	duplicates
	true if storage supports duplicates

Friends
class	::BaseTest

class	::DuplicatesTest

class	::CacheCursorTest

class	::StorageCursorTest

class	Base

class	Cursor< K, V >

Additional Inherited Members
Static Protected Member Functions inherited from LMDBAL::iStorage
template<class T >
static std::string	toString (const T &value)
	A method to cast a value (which can be a value or a key) to string.

Static Protected Attributes inherited from LMDBAL::iStorage
static const std::string	dropMethodName = "drop"
	member function name, just for exceptions

static const std::string	countMethodName = "count"
	member function name, just for exceptions

static const std::string	flagsMethodName = "flags"
	member function name, just for exceptions

static const std::string	addRecordMethodName = "addRecord"
	member function name, just for exceptions

static const std::string	forceRecordMethodName = "forceRecord"
	member function name, just for exceptions

static const std::string	changeRecordMethodName = "changeRecord"
	member function name, just for exceptions

static const std::string	removeRecordMethodName = "removeRecord"
	member function name, just for exceptions

static const std::string	checkRecordMethodName = "checkRecord"
	member function name, just for exceptions

static const std::string	getRecordMethodName = "getRecord"
	member function name, just for exceptions

static const std::string	readAllMethodName = "readAllRecord"
	member function name, just for exceptions

static const std::string	replaceAllMethodName = "replaceAll"
	member function name, just for exceptions

static const std::string	addRecordsMethodName = "addRecords"
	member function name, just for exceptions

Detailed Description

template<class K, class V>
class LMDBAL::Storage< K, V >

This is a basic key value storage.

Template Parameters

K	type of the keys of the storage
V	type of the values of the storage

You can receive an instance of this class calling LMDBAL::Base::addStorage(const std::string&, bool) 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 you didn't save a pointer to the storage at first

You are not supposed to instantiate or destory instances of this class yourself!

Constructor & Destructor Documentation

◆ Storage()

template<class K , class V >

LMDBAL::Storage< K, V >::Storage	(	Base *	parent,
		const std::string &	name,
		bool	duplicates = `false`
	)

protected

Creates a storage.

Parameters

[in]	parent	- LMDBAL::Base pointer for the owning database (borrowed)
[in]	name	- the name of the storage
[in]	duplicates	- true if key duplicates are allowed (false by default)

Member Function Documentation

◆ addRecord() [1/3]

template<class K , class V >

void LMDBAL::Storage< K, V >::addRecord	(	const K &	key,
		const V &	value
	)

virtual

Adds a key-value record to the storage.

Take a note that if the storage already had a record you want to add LMDBAL::Exist is thrown. If your storage doesn't support duplicates LMDBAL::Exist is thrown if the record with the same key already exists in the database. If your storage supports duplicates LMDBAL::Exist is thrown only if the record with the same key AND already exists in the database.

Parameters

[in]	key	key of the record
[in]	value	value of the record

Exceptions

LMDBAL::Exist	thrown if the storage already has a record with the given key
LMDBAL::Closed	thrown if the database was not opened
LMDBAL::Unknown	thrown if something unexpected happend within lmdb

Reimplemented in LMDBAL::Cache< K, V >.

◆ addRecord() [2/3]

template<class K , class V >

void LMDBAL::Storage< K, V >::addRecord	(	const K &	key,
		const V &	value,
		const WriteTransaction &	txn
	)

virtual

Adds a key-value record to the storage (public transaction variant)

This method schedules an addition of a key-value record, but doesn't immidiately adds it. You can obtain LMDBAL::WriteTransaction calling LMDBAL::Base::beginTransaction().

Take a note that if the storage already had a record you want to add LMDBAL::Exist is thrown. If your storage doesn't support duplicates LMDBAL::Exist is thrown if the record with the same key already exists in the database. If your storage supports duplicates LMDBAL::Exist is thrown only if the record with the same key AND already exists in the database.

Parameters

[in]	key	key of the record
[in]	value	value of the record
[in]	txn	transaction

Exceptions

LMDBAL::Exist	thrown if the storage already has a record with the given key
LMDBAL::Closed	thrown if the database was not opened
LMDBAL::Unknown	thrown if something unexpected happend within lmdb
LMDBAL::TransactionTerminated	thrown if the passed transaction not active, any action with it's inner ID is an error

◆ addRecord() [3/3]

template<class K , class V >

void LMDBAL::Storage< K, V >::addRecord	(	const K &	key,
		const V &	value,
		TransactionID	txn
	)

protectedvirtual

Adds a key-value record to the storage (private transaction variant)

Take a note that if the storage already had a record you want to add LMDBAL::Exist is thrown. If your storage doesn't support duplicates LMDBAL::Exist is thrown if the record with the same key already exists in the database. If your storage supports duplicates LMDBAL::Exist is thrown only if the record with the same key AND already exists in the database.

Parameters

[in]	key	key of the record
[in]	value	value of the record
[in]	txn	transaction ID, needs to be a writable transaction!

Exceptions

LMDBAL::Exist	thrown if the storage already has a record with the given key
LMDBAL::Unknown	thrown if something unexpected happend within lmdb

Reimplemented in LMDBAL::Cache< K, V >.

◆ addRecords() [1/3]

template<class K , class V >

uint32_t LMDBAL::Storage< K, V >::addRecords	(	const std::map< K, V > &	data,
		bool	overwrite = `false`
	)

virtual

Adds records in bulk.

Parameters

[in]	data	the data to be added
[in]	overwrite	if false method throws LMDBAL::Exist on repeated key, if true - overwrites it

Returns: new actual amount of records in the storage

Exceptions

LMDBAL::Closed	thrown if the database was not opened
LMDBAL::Exist	thrown if overwrite==false and at least one of the keys of data already exists in the storage
LMDBAL::Unknown	thrown if something unexpected happend within lmdb

Reimplemented in LMDBAL::Cache< K, V >.

◆ addRecords() [2/3]

template<class K , class V >

uint32_t LMDBAL::Storage< K, V >::addRecords	(	const std::map< K, V > &	data,
		const WriteTransaction &	txn,
		bool	overwrite = `false`
	)

virtual

Adds records in bulk (public transaction variant)

This method schedules a data addition, but doesn't immidiately execute it. You can obtain LMDBAL::Transaction calling LMDBAL::Base::beginTransaction().

Parameters

[in]	data	the data to be added
[in]	txn	transaction
[in]	overwrite	if false method throws LMDBAL::Exist on repeated key, if true - overwrites it

Returns: new actual amount of records in the storage

Exceptions

LMDBAL::Closed	thrown if the database was not opened
LMDBAL::Exist	thrown if overwrite==false and at least one of the keys of data already exists in the storage
LMDBAL::Unknown	thrown if something unexpected happend within lmdb
LMDBAL::TransactionTerminated	thrown if the passed transaction not active, any action with it's inner ID is an error

◆ addRecords() [3/3]

template<class K , class V >

uint32_t LMDBAL::Storage< K, V >::addRecords	(	const std::map< K, V > &	data,
		TransactionID	txn,
		bool	overwrite = `false`
	)

protectedvirtual

Adds records in bulk (private transaction variant)

This method schedules a data addition, but doesn't immidiately execute it.

Parameters

[in]	data	the data to be added
[in]	txn	transaction ID, needs to be a writable transaction!
[in]	overwrite	if false method throws LMDBAL::Exist on repeated key, if true - overwrites it

Returns: new actual amount of records in the storage

Exceptions

LMDBAL::Exist	thrown if overwrite==false and at least one of the keys of data already exists in the storage
LMDBAL::Unknown	thrown if something unexpected happend within lmdb

Reimplemented in LMDBAL::Cache< K, V >.

◆ changeRecord() [1/3]

template<class K , class V >

void LMDBAL::Storage< K, V >::changeRecord	(	const K &	key,
		const V &	value
	)

virtual

Changes key-value record to the storage.

Take a note that if the storage didn't have a record you want to change LMDBAL::NotFound is thrown

If duplicates mode is enabled this function will find the first entry of the key (which is pretty couterintuitive, see LMDBAL::Storage::getRecord() description) and change it's value to the given one. If the given value matches some of the other values for given key the method will throw LMDBAL::Exist, if no key was found it will still throw LMDBAL::NotFound.

Parameters

[in]	key	key of the record
[in]	value	new value of the record

Exceptions

LMDBAL::NotFound	thrown if the storage doesn't have a record with the given key
LMDBAL::Exist	thrown in duplicates mode when the given value matches some of existing values for the given key
LMDBAL::Closed	thrown if the database was not opened
LMDBAL::Unknown	thrown if something unexpected happend within lmdb

Reimplemented in LMDBAL::Cache< K, V >.

◆ changeRecord() [2/3]

template<class K , class V >

void LMDBAL::Storage< K, V >::changeRecord	(	const K &	key,
		const V &	value,
		const WriteTransaction &	txn
	)

virtual

Changes key-value record to the storage (public transaction variant)

This method schedules a modification of a key-value record, but doesn't immidiately changes it. You can obtain LMDBAL::WriteTransaction calling LMDBAL::Base::beginTransaction().

Take a note that if the storage didn't have a record you want to change LMDBAL::NotFound is thrown

If duplicates mode is enabled this function will find the first entry of the key (which is pretty couterintuitive, see LMDBAL::Storage::getRecord() description) and change it's value to the given one. If the given value matches some of the other values for given key the method will throw LMDBAL::Exist, if no key was found it will still throw LMDBAL::NotFound.

Parameters

[in]	key	key of the record
[in]	value	new value of the record
[in]	txn	transaction

Exceptions

LMDBAL::NotFound	thrown if the storage doesn't have a record with the given key
LMDBAL::Exist	thrown in duplicates mode when the given value matches some of existing values for the given key
LMDBAL::Closed	thrown if the database was not opened
LMDBAL::Unknown	thrown if something unexpected happend within lmdb
LMDBAL::TransactionTerminated	thrown if the passed transaction not active, any action with it's inner ID is an error

◆ changeRecord() [3/3]

template<class K , class V >

void LMDBAL::Storage< K, V >::changeRecord	(	const K &	key,
		const V &	value,
		TransactionID	txn
	)

protectedvirtual

Changes key-value record to the storage (private transaction variant)

This method schedules a modification of a key-value record, but doesn't immidiately changes it. Take a note that if the storage didn't have a record you want to change LMDBAL::NotFound is thrown

If duplicates mode is enabled this function will find the first entry of the key (which is pretty couterintuitive, see LMDBAL::Storage::getRecord() description) and change it's value to the given one. If the given value matches some of the other values for given key the method will throw LMDBAL::Exist, if no key was found it will still throw LMDBAL::NotFound.

Parameters

[in]	key	key of the record
[in]	value	new value of the record
[in]	txn	transaction ID, needs to be a writable transaction!

Exceptions

LMDBAL::NotFound	thrown if the storage doesn't have a record with the given key
LMDBAL::Exist	thrown in duplicates mode when the given value matches some of existing values for the given key
LMDBAL::Unknown	thrown if something unexpected happend within lmdb

Reimplemented in LMDBAL::Cache< K, V >.

◆ checkRecord() [1/3]

template<class K , class V >

bool LMDBAL::Storage< K, V >::checkRecord ( const K & key ) const

virtual

Chechs if storage has value.

Parameters

[in] key key of the record you look for

Returns: true if there was a record with given key, false otherwise

Exceptions

LMDBAL::Closed	thrown if the database was not opened
LMDBAL::Unknown	thrown if something unexpected happend within lmdb

Reimplemented in LMDBAL::Cache< K, V >.

◆ checkRecord() [2/3]

template<class K , class V >

bool LMDBAL::Storage< K, V >::checkRecord	(	const K &	key,
		const Transaction &	txn
	)		const

virtual

Chechs if storage has value (public transaction variant)

You can obtain LMDBAL::Transaction calling LMDBAL::Base::beginReadOnlyTransaction() or LMDBAL::Base::beginTransaction(). If you just want to read data you should prefer LMDBAL::Base::beginReadOnlyTransaction().

Parameters

[in]	key	key of the record you look for
[in]	txn	transaction, can be read only transaction

Returns: true if there was a record with given key, false otherwise

Exceptions

LMDBAL::Closed	thrown if the database was not opened
LMDBAL::Unknown	thrown if something unexpected happend within lmdb
LMDBAL::TransactionTerminated	thrown if the passed transaction not active, any action with it's inner ID is an error

◆ checkRecord() [3/3]

template<class K , class V >

bool LMDBAL::Storage< K, V >::checkRecord	(	const K &	key,
		TransactionID	txn
	)		const

protectedvirtual

Chechs if storage has value (private transaction variant)

Parameters

[in]	key	key of the record you look for
[in]	txn	transaction ID, can be read only transaction

Returns: true if there was a record with given key, false otherwise

Exceptions

LMDBAL::Unknown thrown if something unexpected happend within lmdb

Reimplemented in LMDBAL::Cache< K, V >.

◆ close()

template<class K , class V >

void LMDBAL::Storage< K, V >::close ( )

overrideprotectedvirtual

A private virtual method I need to close each storage in the database.

Reimplemented from LMDBAL::iStorage.

◆ createCursor()

template<class K , class V >

LMDBAL::Cursor< K, V > LMDBAL::Storage< K, V >::createCursor ( )

Creates cursor.

This is a legitimate way to aquire cursor to a storage. Aquired cursor is RAII safe, automatic destructor will free everything it occupied.

Returns: LMDBAL::Cursor for this storage and returs you a pointer to a created cursor

◆ destroyCursor()

template<class K , class V >

void LMDBAL::Storage< K, V >::destroyCursor ( LMDBAL::Cursor< K, V > & cursor )

Frees cursor.

This is a legitimate way to free cursor. You don't actually need to do it manually, you can just reassign cursor, let it be destroyed by leaving the scope or call LMDBAL::Cursor<K, V>::drop, but you may if you wish.

Parameters

[in] cursor cursor you wish to destroy

Exceptions

LMDBAL::Unknown thrown if you try to destroy a cursor this storage didn't create

◆ discoveredRecord() [1/2]

template<class K , class V >

void LMDBAL::Storage< K, V >::discoveredRecord	(	const K &	key,
		const V &	value
	)		const

protectedvirtual

A private virtual method that cursor calls when he reads a record, does nothing here but populates the LMDBAL::Cache.

Parameters

[in]	key	a key of discovered record
[in]	value	a value of discovered record

Reimplemented in LMDBAL::Cache< K, V >.

◆ discoveredRecord() [2/2]

template<class K , class V >

void LMDBAL::Storage< K, V >::discoveredRecord	(	const K &	key,
		const V &	value,
		TransactionID	txn
	)		const

protectedvirtual

A private virtual method that cursor calls when he reads a record, does nothing here but populates the LMDBAL::Cache.

Parameters

[in]	key	a key of discovered record
[in]	value	a value of discovered record
[in]	txn	TransactionID under which the dicovery happened, to avoid not commited changes collisions

Reimplemented in LMDBAL::Cache< K, V >.

◆ drop() [1/3]

template<class K , class V >

void LMDBAL::iStorage::drop ( )

virtual

Drops content of a storage interface.

Designed to drop storage content

Exceptions

LMDBAL::Closed	thrown if the database was closed
LMDBAL::Unknown	thrown if something unexpected happened

Reimplemented from LMDBAL::iStorage.

◆ drop() [2/3]

template<class K , class V >

int LMDBAL::iStorage::drop ( const WriteTransaction & txn )

virtual

Drops content of a storage interface (public transaction variant)

Just performs content drop

Parameters

[in] txn - transaction ID, must be writable transaction!

Returns: MDB_SUCCESS if everything went fine, MDB_<error> code otherwise

Exceptions

LMDBAL::TransactionTerminated thrown if the transaction was not active

Reimplemented from LMDBAL::iStorage.

◆ drop() [3/3]

template<class K , class V >

int LMDBAL::iStorage::drop ( TransactionID transaction )

virtual

Drops content of a storage interface (transaction variant)

Just performs content drop

Parameters

[in] transaction - transaction ID, must be writable transaction!

Returns: MDB_SUCCESS if everything went fine, MDB_<error> code otherwise

Reimplemented from LMDBAL::iStorage.

◆ flags()

template<class K , class V >

uint32_t LMDBAL::Storage< K, V >::flags ( ) const

protected

Reads current storage flags it was opened with.

This method exists mostly for testing purposes

Returns: Third out parameter of mdb_dbi_flags function

Exceptions

LMDBAL::Closed	thrown if the database was not opened
LMDBAL::Unknown	if the result of mdb_dbi_flags was not successfull

◆ forceRecord() [1/3]

template<class K , class V >

bool LMDBAL::Storage< K, V >::forceRecord	(	const K &	key,
		const V &	value
	)

virtual

Adds a key-value record to the storage, overwrites if it already exists.

This method is mostly useless in duplicates mode. In this mode it basically does the same thing LMDBAL::Storage::addRecord() does, but suppresses LMDBAL::Exist exception if the record with the same key-value pair existed in the storage. In this case just false is returned from the method.

Parameters

[in]	key	key of the record
[in]	value	value of the record

Returns: true if the record was added, false otherwise

Exceptions

LMDBAL::Closed	thrown if the database was not opened
LMDBAL::Unknown	thrown if something unexpected happend within lmdb

Reimplemented in LMDBAL::Cache< K, V >.

◆ forceRecord() [2/3]

template<class K , class V >

bool LMDBAL::Storage< K, V >::forceRecord	(	const K &	key,
		const V &	value,
		const WriteTransaction &	txn
	)

virtual

Adds a key-value record to the storage, overwrites if it already exists (public transaction variant)

This method schedules an addition of a key-value record, but doesn't immidiately add it. You can obtain LMDBAL::WriteTransaction calling LMDBAL::Base::beginTransaction(). If the record did already exist in the database the actual overwrite will be done only after calling LMDBAL::WriteTransaction::commit().

This method is mostly useless in duplicates mode. In this mode it basically does the same thing LMDBAL::Storage::addRecord() does, but suppresses LMDBAL::Exist exception if the record with the same key-value pair existed in the storage. In this case just false is returned from the method.

Parameters

[in]	key	key of the record
[in]	value	value of the record
[in]	txn	transaction

Returns: true if the record was added, false otherwise

Exceptions

LMDBAL::Closed	thrown if the database was not opened
LMDBAL::Unknown	thrown if something unexpected happend within lmdb
LMDBAL::TransactionTerminated	thrown if the passed transaction not active, any action with it's inner ID is an error

◆ forceRecord() [3/3]

template<class K , class V >

bool LMDBAL::Storage< K, V >::forceRecord	(	const K &	key,
		const V &	value,
		TransactionID	txn
	)

protectedvirtual

Adds a key-value record to the storage, overwrites if it already exists (private transaction variant)

This method schedules an addition of a key-value record, but doesn't immidiately add it.

This method is mostly useless in duplicates mode. In this mode it basically does the same thing LMDBAL::Storage::addRecord() does, but suppresses LMDBAL::Exist exception if the record with the same key-value pair existed in the storage. In this case just false is returned from the method.

Parameters

[in]	key	key of the record
[in]	value	value of the record
[in]	txn	transaction ID, needs to be a writable transaction!

Returns: true if the record was added, false otherwise

Exceptions

LMDBAL::Unknown thrown if something unexpected happend within lmdb

Reimplemented in LMDBAL::Cache< K, V >.

◆ getRecord() [1/6]

template<class K , class V >

V LMDBAL::Storage< K, V >::getRecord ( const K & key ) const

virtual

Gets the record from the database.

Take a note that if the storage didn't have a record you want to get LMDBAL::NotFound is thrown

If the storage supports duplicates the exact value returned from it depends on comparison function of lmdb. It's not very straight forward, so, you shouldn't really use this method if you use duplicates and you rely on exact result. Anyway:

if your values are signed or unsigned integer of any size the LOWEST value is returned compared as UNSIGNED. For example for storage with int32_t as value, from the same key, from the set of values {-33, -1, 5573, 77753} 5573 is returned as it is the lowest by UNSIGNED comparison.
if your values are anything else - they are compared byte by byte as if they are strings, it makes it especially complicated to predict the exact value for float or double templated storages. For strings if makes a bit more sence: if the choise is from "50" and "100" - "100" is returned, because the first byte of the "100" is lower than the first byte of the "50"

Parameters

[in] key key of the record you look for

Returns: the value from the storage

Exceptions

LMDBAL::NotFound	thrown if the storage doesn't have a record with the given key
LMDBAL::Closed	thrown if the database was not opened
LMDBAL::Unknown	thrown if something unexpected happend within lmdb

Reimplemented in LMDBAL::Cache< K, V >.

◆ getRecord() [2/6]

template<class K , class V >

V LMDBAL::Storage< K, V >::getRecord	(	const K &	key,
		const Transaction &	txn
	)		const

virtual

Gets the record from the database (public transaction variant)

You can obtain LMDBAL::Transaction calling LMDBAL::Base::beginReadOnlyTransaction() or LMDBAL::Base::beginTransaction(). If you just want to read data you should prefer LMDBAL::Base::beginReadOnlyTransaction().

Take a note that if the storage didn't have a record you want to get LMDBAL::NotFound is thrown

If the storage supports duplicates the exact value returned from it depends on comparison function of lmdb. It's not very straight forward, so, you shouldn't really use this method if you use duplicates and you rely on exact result. Anyway:

if your values are signed or unsigned integer of any size the LOWEST value is returned compared as UNSIGNED. For example for storage with int32_t as value, from the same key, from the set of values {-33, -1, 5573, 77753} 5573 is returned as it is the lowest by UNSIGNED comparison.
if your values are anything else - they are compared byte by byte as if they are strings, it makes it especially complicated to predict the exact value for float or double templated storages. For strings if makes a bit more sence: if the choise is from "50" and "100" - "100" is returned, because the first byte of the "100" is lower than the first byte of the "50"

Parameters

[in]	key	key of the record you look for
[in]	txn	transaction ID, can be read only transaction

Returns: the value from the storage

Exceptions

LMDBAL::NotFound	thrown if the storage doesn't have a record with the given key
LMDBAL::Closed	thrown if the database was not opened
LMDBAL::Unknown	thrown if something unexpected happend within lmdb
LMDBAL::TransactionTerminated	thrown if the passed transaction not active, any action with it's inner ID is an error

◆ getRecord() [3/6]

template<class K , class V >

V LMDBAL::Storage< K, V >::getRecord	(	const K &	key,
		TransactionID	txn
	)		const

protectedvirtual

Gets the record from the database (private transaction variant)

Take a note that if the storage didn't have a record you want to get LMDBAL::NotFound is thrown

If the storage supports duplicates the exact value returned from it depends on comparison function of lmdb. It's not very straight forward, so, you shouldn't really use this method if you use duplicates and you rely on exact result. Anyway:

if your values are signed or unsigned integer of any size the LOWEST value is returned compared as UNSIGNED. For example for storage with int32_t as value, from the same key, from the set of values {-33, -1, 5573, 77753} 5573 is returned as it is the lowest by UNSIGNED comparison.
if your values are anything else - they are compared byte by byte as if they are strings, it makes it especially complicated to predict the exact value for float or double templated storages. For strings if makes a bit more sence: if the choise is from "50" and "100" - "100" is returned, because the first byte of the "100" is lower than the first byte of the "50"

Parameters

[in]	key	key of the record you look for
[in]	txn	transaction ID, can be read only transaction

Returns: the value from the storage

Exceptions

LMDBAL::NotFound	thrown if the storage doesn't have a record with the given key
LMDBAL::Unknown	thrown if something unexpected happend within lmdb

Reimplemented in LMDBAL::Cache< K, V >.

◆ getRecord() [4/6]

template<class K , class V >

void LMDBAL::Storage< K, V >::getRecord	(	const K &	key,
		V &	value
	)		const

virtual

Gets the record from the database (reference variant)

Take a note that if the storage didn't have a record you want to get LMDBAL::NotFound is thrown

If the storage supports duplicates the exact value returned from it depends on comparison function of lmdb. It's not very straight forward, so, you shouldn't really use this method if you use duplicates and you rely on exact result. Anyway:

if your values are signed or unsigned integer of any size the LOWEST value is returned compared as UNSIGNED. For example for storage with int32_t as value, from the same key, from the set of values {-33, -1, 5573, 77753} 5573 is returned as it is the lowest by UNSIGNED comparison.
if your values are anything else - they are compared byte by byte as if they are strings, it makes it especially complicated to predict the exact value for float or double templated storages. For strings if makes a bit more sence: if the choise is from "50" and "100" - "100" is returned, because the first byte of the "100" is lower than the first byte of the "50"

Parameters

[in]	key	key of the record you look for
[out]	value	the value from the storage

Exceptions

LMDBAL::NotFound	thrown if the storage doesn't have a record with the given key
LMDBAL::Closed	thrown if the database was not opened
LMDBAL::Unknown	thrown if something unexpected happend within lmdb

Reimplemented in LMDBAL::Cache< K, V >.

◆ getRecord() [5/6]

template<class K , class V >

void LMDBAL::Storage< K, V >::getRecord	(	const K &	key,
		V &	value,
		const Transaction &	txn
	)		const

virtual

Gets the record from the database (public transaction, reference variant)

You can obtain LMDBAL::Transaction calling LMDBAL::Base::beginReadOnlyTransaction() or LMDBAL::Base::beginTransaction(). If you just want to read data you should prefer LMDBAL::Base::beginReadOnlyTransaction().

Take a note that if the storage didn't have a record you want to get LMDBAL::NotFound is thrown

If the storage supports duplicates the exact value returned from it depends on comparison function of lmdb. It's not very straight forward, so, you shouldn't really use this method if you use duplicates and you rely on exact result. Anyway:

if your values are signed or unsigned integer of any size the LOWEST value is returned compared as UNSIGNED. For example for storage with int32_t as value, from the same key, from the set of values {-33, -1, 5573, 77753} 5573 is returned as it is the lowest by UNSIGNED comparison.
if your values are anything else - they are compared byte by byte as if they are strings, it makes it especially complicated to predict the exact value for float or double templated storages. For strings if makes a bit more sence: if the choise is from "50" and "100" - "100" is returned, because the first byte of the "100" is lower than the first byte of the "50"

Parameters

[in]	key	key of the record you look for
[out]	value	the value from the storage
[in]	txn	transaction ID, can be read only transaction

Exceptions

LMDBAL::NotFound	thrown if the storage doesn't have a record with the given key
LMDBAL::Closed	thrown if the database was not opened
LMDBAL::Unknown	thrown if something unexpected happend within lmdb
LMDBAL::TransactionTerminated	thrown if the passed transaction not active, any action with it's inner ID is an error

◆ getRecord() [6/6]

template<class K , class V >

void LMDBAL::Storage< K, V >::getRecord	(	const K &	key,
		V &	value,
		TransactionID	txn
	)		const

protectedvirtual

Gets the record from the database (private transaction, reference variant)

Take a note that if the storage didn't have a record you want to get LMDBAL::NotFound is thrown

If the storage supports duplicates the exact value returned from it depends on comparison function of lmdb. It's not very straight forward, so, you shouldn't really use this method if you use duplicates and you rely on exact result. Anyway:

if your values are signed or unsigned integer of any size the LOWEST value is returned compared as UNSIGNED. For example for storage with int32_t as value, from the same key, from the set of values {-33, -1, 5573, 77753} 5573 is returned as it is the lowest by UNSIGNED comparison.
if your values are anything else - they are compared byte by byte as if they are strings, it makes it especially complicated to predict the exact value for float or double templated storages. For strings if makes a bit more sence: if the choise is from "50" and "100" - "100" is returned, because the first byte of the "100" is lower than the first byte of the "50"

Parameters

[in]	key	key of the record you look for
[out]	value	the value from the storage
[in]	txn	transaction ID, can be read only transaction

Exceptions

LMDBAL::NotFound	thrown if the storage doesn't have a record with the given key
LMDBAL::Unknown	thrown if something unexpected happend within lmdb

Reimplemented in LMDBAL::Cache< K, V >.

◆ open()

template<class K , class V >

int LMDBAL::Storage< K, V >::open ( MDB_txn * transaction )

overrideprotectedvirtual

A private virtual method I need to open each storage in the database.

Parameters

[in] transaction - lmdb transaction to call mdb_dbi_open

Returns: MDB_SUCCESS if everything went smooth or MDB_<error> -like error code

Implements LMDBAL::iStorage.

◆ readAll() [1/6]

template<class K , class V >

std::map< K, V > LMDBAL::Storage< K, V >::readAll ( ) const

virtual

Reads whole storage into a map.

Basically just reads all database in an std::map, usefull when you store small storages

In case storage supports duplicates only what lmdb considered to be lowest value (see LMDBAL::Storage::getRecord() description) is returned in the resulting map

Exceptions

LMDBAL::Closed	thrown if the database was not opened
LMDBAL::Unknown	thrown if something unexpected happend within lmdb

Reimplemented in LMDBAL::Cache< K, V >.

◆ readAll() [2/6]

template<class K , class V >

std::map< K, V > LMDBAL::Storage< K, V >::readAll ( const Transaction & txn ) const

virtual

Reads whole storage into a map (public 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().

In case storage supports duplicates only what lmdb considered to be lowest value (see LMDBAL::Storage::getRecord() description) is returned in the resulting map

Parameters

[in] txn transaction, can be read only transaction

Exceptions

LMDBAL::Closed	thrown if the database was not opened
LMDBAL::Unknown	thrown if something unexpected happend within lmdb
LMDBAL::TransactionTerminated	thrown if the passed transaction not active, any action with it's inner ID is an error

◆ readAll() [3/6]

template<class K , class V >

void LMDBAL::Storage< K, V >::readAll ( std::map< K, V > & result ) const

virtual

Reads whole storage into a map (reference variant)

Basically just reads all database in an std::map, usefull when you store small storages

In case storage supports duplicates only what lmdb considered to be lowest value (see LMDBAL::Storage::getRecord() description) is returned in the resulting map

Parameters

[out] result a map that is going to contain all data

Exceptions

LMDBAL::Closed	thrown if the database was not opened
LMDBAL::Unknown	thrown if something unexpected happend within lmdb

Reimplemented in LMDBAL::Cache< K, V >.

◆ readAll() [4/6]

template<class K , class V >

void LMDBAL::Storage< K, V >::readAll	(	std::map< K, V > &	result,
		const Transaction &	txn
	)		const

virtual

Reads whole storage into a map (public transaction, reference variant)

Basically just reads all database in an std::map, usefull when you store small storages You can obtain LMDBAL::Transaction calling LMDBAL::Base::beginReadOnlyTransaction() or LMDBAL::Base::beginTransaction(). If you just want to read data you should prefer LMDBAL::Base::beginReadOnlyTransaction().

In case storage supports duplicates only what lmdb considered to be lowest value (see LMDBAL::Storage::getRecord() description) is returned in the resulting map

Parameters

[out]	result	a map that is going to contain all data
[in]	txn	transaction, can be read only transaction

Exceptions

LMDBAL::Closed	thrown if the database was not opened
LMDBAL::Unknown	thrown if something unexpected happend within lmdb
LMDBAL::TransactionTerminated	thrown if the passed transaction not active, any action with it's inner ID is an error

◆ readAll() [5/6]

template<class K , class V >

void LMDBAL::Storage< K, V >::readAll	(	std::map< K, V > &	result,
		TransactionID	txn
	)		const

protectedvirtual

Reads whole storage into a map (private transaction, reference variant)

Basically just reads all database in an std::map, usefull when you store small storages In case storage supports duplicates only what lmdb considered to be lowest value (see LMDBAL::Storage::getRecord() description) is returned in the resulting map

Parameters

[out]	result	a map that is going to contain all data
[in]	txn	transaction ID, can be read only transaction

Exceptions

LMDBAL::Unknown thrown if something unexpected happend within lmdb

Reimplemented in LMDBAL::Cache< K, V >.

◆ readAll() [6/6]

template<class K , class V >

std::map< K, V > LMDBAL::Storage< K, V >::readAll ( TransactionID txn ) const

protectedvirtual

Reads whole storage into a map (private transaction variant)

Basically just reads all database in an std::map, usefull when you store small storages In case storage supports duplicates only what lmdb considered to be lowest value (see LMDBAL::Storage::getRecord() description) is returned in the resulting map

Parameters

[in] txn transaction ID, can be read only transaction

Exceptions

LMDBAL::Unknown thrown if something unexpected happend within lmdb

Reimplemented in LMDBAL::Cache< K, V >.

◆ removeRecord() [1/3]

template<class K , class V >

void LMDBAL::Storage< K, V >::removeRecord ( const K & key )

virtual

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

Parameters

[in] key key of the record you wish to be removed

Exceptions

LMDBAL::Closed	thrown if the database was not opened
LMDBAL::NotFound	thrown if the record with given key wasn't found
LMDBAL::Unknown	thrown if something unexpected happend within lmdb

Reimplemented in LMDBAL::Cache< K, V >.

◆ removeRecord() [2/3]

template<class K , class V >

void LMDBAL::Storage< K, V >::removeRecord	(	const K &	key,
		const WriteTransaction &	txn
	)

virtual

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 method schedules a record removal, but doesn't immidiately execute it. You can obtain LMDBAL::Transaction calling LMDBAL::Base::beginTransaction().

Parameters

[in]	key	key of the record you wish to be removed
[in]	txn	transaction ID

Exceptions

LMDBAL::Closed	thrown if the database was not opened
LMDBAL::NotFound	thrown if the record with given key wasn't found
LMDBAL::Unknown	thrown if something unexpected happend within lmdb
LMDBAL::TransactionTerminated	thrown if the passed transaction not active, any action with it's inner ID is an error

◆ removeRecord() [3/3]

template<class K , class V >

void LMDBAL::Storage< K, V >::removeRecord	(	const K &	key,
		TransactionID	txn
	)

protectedvirtual

Removes one of the records (private transaction variant)

Take a note that if the storage didn't have a record you want to remove LMDBAL::NotFound is thrown This method schedules a record removal, but doesn't immidiately execute it.

Parameters

[in]	key	key of the record you wish to be removed
[in]	txn	transaction ID, needs to be a writable transaction!

Exceptions

LMDBAL::NotFound	thrown if the record with given key wasn't found
LMDBAL::Unknown	thrown if something unexpected happend within lmdb

Reimplemented in LMDBAL::Cache< K, V >.

◆ replaceAll() [1/3]

template<class K , class V >

void LMDBAL::Storage< K, V >::replaceAll ( const std::map< K, V > & data )

virtual

Replaces the content of the whole storage with the given.

Basically this method drops the database and adds all the records from the given map

Parameters

[in] data new data of the storage

Exceptions

LMDBAL::Closed	thrown if the database was not opened
LMDBAL::Unknown	thrown if something unexpected happend within lmdb

Reimplemented in LMDBAL::Cache< K, V >.

◆ replaceAll() [2/3]

template<class K , class V >

void LMDBAL::Storage< K, V >::replaceAll	(	const std::map< K, V > &	data,
		const WriteTransaction &	txn
	)

virtual

Replaces the content of the whole storage with the given (public transaction variant)

Basically this method drops the database and adds all the records from the given map This method schedules a data replacement, but doesn't immidiately execute it. You can obtain LMDBAL::Transaction calling LMDBAL::Base::beginTransaction().

Parameters

[in]	data	new data of the storage
[in]	txn	transaction

Exceptions

LMDBAL::Closed	thrown if the database was not opened
LMDBAL::Unknown	thrown if something unexpected happend within lmdb
LMDBAL::TransactionTerminated	thrown if the passed transaction not active, any action with it's inner ID is an error

◆ replaceAll() [3/3]

template<class K , class V >

void LMDBAL::Storage< K, V >::replaceAll	(	const std::map< K, V > &	data,
		TransactionID	txn
	)

protectedvirtual

Replaces the content of the whole storage with the given (private transaction variant)

Basically this method drops the database and adds all the records from the given map

Parameters

[in]	data	new data of the storage
[in]	txn	transaction ID, needs to be a writable transaction!

Exceptions

LMDBAL::Unknown thrown if something unexpected happend within lmdb

Reimplemented in LMDBAL::Cache< K, V >.

The documentation for this class was generated from the following files:

/workspace/blue/lmdbal/src/base.h
/workspace/blue/lmdbal/src/storage.h
/workspace/blue/lmdbal/src/storage.hpp

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Storage()

Member Function Documentation

◆ addRecord() [1/3]

◆ addRecord() [2/3]

◆ addRecord() [3/3]

◆ addRecords() [1/3]

◆ addRecords() [2/3]

◆ addRecords() [3/3]

◆ changeRecord() [1/3]

◆ changeRecord() [2/3]

◆ changeRecord() [3/3]

◆ checkRecord() [1/3]

◆ checkRecord() [2/3]

◆ checkRecord() [3/3]

◆ close()

◆ createCursor()

◆ destroyCursor()

◆ discoveredRecord() [1/2]

◆ discoveredRecord() [2/2]

◆ drop() [1/3]

◆ drop() [2/3]

◆ drop() [3/3]

◆ flags()

◆ forceRecord() [1/3]

◆ forceRecord() [2/3]

◆ forceRecord() [3/3]

◆ getRecord() [1/6]

◆ getRecord() [2/6]

◆ getRecord() [3/6]

◆ getRecord() [4/6]

◆ getRecord() [5/6]

◆ getRecord() [6/6]

◆ open()

◆ readAll() [1/6]

◆ readAll() [2/6]

◆ readAll() [3/6]

◆ readAll() [4/6]

◆ readAll() [5/6]

◆ readAll() [6/6]

◆ removeRecord() [1/3]

◆ removeRecord() [2/3]

◆ removeRecord() [3/3]

◆ replaceAll() [1/3]

◆ replaceAll() [2/3]

◆ replaceAll() [3/3]