stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl Class Reference

Implementation class used to read constant B-tree database files. More...

#include <stx-cbtreedb.h>

Collaboration diagram for stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl:

Public Member Functions
	ReaderImpl (const key_compare &key_less)
	Create new reader, which is initially set to closed state.
void	RefInc ()
	Increment reference counter by one.
unsigned int	RefDec ()
	Decrement reference counter by one and return it.
void	SetSignature (const char *newsignature)
	Change the database signature (first 8 bytes) from 'cbtreedb' to a custom string.
bool	Open (std::istream &file, std::string *errortext=NULL)
	Attempt to open a cbtreedb database file.
void	Close ()
	Close the opened database.
void	SetPageCache (PageCache *newpagecache)
	Change the currently used page cache object.
uint32_t	Size () const
	Returns the number of items in the loaded database.
const SignaturePage &	GetSignature () const
	Returns a const reference to the signature page of the currently loaded database.
bool	Exists (const key_type &key)
	Check if a key is in the constant database.
bool	Lookup (const key_type &key, void *outvalue, uint32_t maxsize)
	Find a key in the constant database.
bool	Lookup (const key_type &key, std::string &outvalue)
	Find a key in the constant database.
std::string	operator[] (const key_type &key)
	Find a key in the constant database.
uint32_t	GetIndex (uint32_t index, key_type &outkey)
	Returns only the key by index.
uint32_t	GetIndex (uint32_t index, key_type &outkey, void *outvalue, uint32_t maxsize)
	Return a key and associated value by index.
uint32_t	GetIndex (uint32_t index, key_type &outkey, std::string &outvalue)
	Return a key and associated value by index.
bool	Verify ()
	Verify all aspects of the loaded database.
bool	VerifyBTree ()
	Verify B-tree structure in the loaded database.
bool	VerifyBTreeChecksum ()
	Verify the SHA256 checksum of the B-tree pages in the loaded database.
bool	VerifyValueChecksum ()
	Verify the SHA256 checksum of value data area in the loaded database.
Protected Member Functions
BTreePage	ReadIndexPage (uint32_t pageoffset)
	Read one B-tree page from the file (or from cache).
bool	ReadValueRange (uint64_t offset, void *data, uint32_t size)
	Read byte range [offset, offset+size) from value data area into the given buffer.
bool	KeyEqual (const key_type &a, const key_type &b)
	Function to test key equality, constructed from m_key_less.
bool	KeyUnequal (const key_type &a, const key_type &b)
	Function to test key inequality, constructed from m_key_less.
template<typename NodeType >
int	BinarySearch (const NodeType *node, key_type key)
	Find the first key slot containing a greater-or-equal key.
bool	FindKey (const key_type &key, uint64_t &outoffset, uint32_t &outsize)
	Internal function to look down the B-tree and find a key.
bool	FindIndex (uint32_t index, key_type &outkey, uint64_t &outoffset, uint32_t &outsize)
	Internal function to look directly into the B-tree's leaf pages and find a key by index.
bool	VerifyBTreeNode (uint32_t offset, key_type minkey, key_type maxkey, uint64_t *lastoffset)
	Internal function: Recursively verify B-tree structure.
Protected Attributes
unsigned int	m_refs
	reference counter
key_compare	m_key_less
	key comparison functional
char	m_signaturestr [8]
	signature characters to expect file to begin with.
std::istream *	m_istream
	file stream object currently opened.
SignaturePage	m_signature
	signature page read from file
PageCache *	m_pagecache
	pointer to b-tree page cache to used.

Detailed Description

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>
class stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl

Implementation class used to read constant B-tree database files.

Refer to Design Principles and Database Architecture and Example Usage on how to use this class.

Definition at line 1419 of file stx-cbtreedb.h.

Constructor & Destructor Documentation

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::ReaderImpl ( const key_compare & key_less ) [inline]

Create new reader, which is initially set to closed state.

Definition at line 1535 of file stx-cbtreedb.h.

Member Function Documentation

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

template<typename NodeType >

int stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::BinarySearch	(	const NodeType *	node,
		key_type	key
	)			`[inline, protected]`

Find the first key slot containing a greater-or-equal key.

Definition at line 1504 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

void stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::Close ( ) [inline]

Close the opened database.

Definition at line 1666 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

bool stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::Exists ( const key_type & key ) [inline]

Check if a key is in the constant database.

Parameters:

key

key to lookup

Returns:: true if found.

Definition at line 1769 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

bool stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::FindIndex	(	uint32_t	index,
		key_type &	outkey,
		uint64_t &	outoffset,
		uint32_t &	outsize
	)			`[inline, protected]`

Internal function to look directly into the B-tree's leaf pages and find a key by index.

If found, returns the key, offset and size of the corresponding value area.

Definition at line 1860 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

bool stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::FindKey	(	const key_type &	key,
		uint64_t &	outoffset,
		uint32_t &	outsize
	)			`[inline, protected]`

Internal function to look down the B-tree and find a key.

If found, returns the offset and size of the corresponding value data area.

Definition at line 1702 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

uint32_t stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::GetIndex	(	uint32_t	index,
		key_type &	outkey,
		std::string &	outvalue
	)			`[inline]`

Return a key and associated value by index.

Looks directly into the leaf pages.

Parameters:

	index	zero-based index of item to retrieve
	outkey	set to key of item
	outvalue	string to hold data of value

Returns:: size of associated value

Definition at line 1951 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

uint32_t stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::GetIndex	(	uint32_t	index,
		key_type &	outkey,
		void *	outvalue,
		uint32_t	maxsize
	)			`[inline]`

Return a key and associated value by index.

Looks directly into the leaf pages.

Parameters:

	index	zero-based index of item to retrieve
	outkey	set to key of item
	outvalue	buffer to hold data of value
	maxsize	maximum size of buffer

Returns:: size of associated value

Definition at line 1923 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

uint32_t stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::GetIndex	(	uint32_t	index,
		key_type &	outkey
	)			`[inline]`

Returns only the key by index.

Looks directly into the leaf pages.

Parameters:

	index	zero-based index of item to retrieve
	outkey	set to key of item

Returns:: size of associated value if found

Definition at line 1900 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

const SignaturePage& stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::GetSignature ( ) const [inline]

Returns a const reference to the signature page of the currently loaded database.

Definition at line 1692 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

bool stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::KeyEqual	(	const key_type &	a,
		const key_type &	b
	)			`[inline, protected]`

Function to test key equality, constructed from m_key_less.

Definition at line 1491 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

bool stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::KeyUnequal	(	const key_type &	a,
		const key_type &	b
	)			`[inline, protected]`

Function to test key inequality, constructed from m_key_less.

Definition at line 1497 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

bool stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::Lookup	(	const key_type &	key,
		std::string &	outvalue
	)			`[inline]`

Find a key in the constant database.

If found the coresponding value is copied into the output string buffer.

Parameters:

	key	key to lookup
	outvalue	string filled with the associated value if the key is found

Returns:: true if found.

Definition at line 1812 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

bool stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::Lookup	(	const key_type &	key,
		void *	outvalue,
		uint32_t	maxsize
	)			`[inline]`

Find a key in the constant database.

If found the corresponding value is copied into the output buffer.

Parameters:

	key	key to lookup
	outvalue	buffer filled with the associated value if the key is found
	maxsize	maximum size of buffer

Returns:: true if found.

Definition at line 1788 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

bool stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::Open	(	std::istream &	file,
		std::string *	errortext = `NULL`
	)			`[inline]`

Attempt to open a cbtreedb database file.

Reads and verifies the signature and initializes the reader. Note that this function does not through an exception if the file could not be loaded! The istream object must exist as long as the Reader is used.

Parameters:

	file	database file input stream to attach.
	errortext	in case of error, set to an informative text.

Returns:: true if loaded and verified correctly.

Definition at line 1578 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

std::string stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::operator[] ( const key_type & key ) [inline]

Find a key in the constant database.

If found the corresponding value is copied into the output string buffer. If the key does not exist, an empty string is returned.

Parameters:

key

key to lookup

Returns:: string containing the value

Definition at line 1835 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

BTreePage stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::ReadIndexPage ( uint32_t pageoffset ) [inline, protected]

Read one B-tree page from the file (or from cache).

Definition at line 1442 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

bool stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::ReadValueRange	(	uint64_t	offset,
		void *	data,
		uint32_t	size
	)			`[inline, protected]`

Read byte range [offset, offset+size) from value data area into the given buffer.

Definition at line 1475 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

unsigned int stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::RefDec ( ) [inline]

Decrement reference counter by one and return it.

Definition at line 1548 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

void stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::RefInc ( ) [inline]

Increment reference counter by one.

Definition at line 1542 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

void stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::SetPageCache ( PageCache * newpagecache ) [inline]

Change the currently used page cache object.

Definition at line 1673 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

void stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::SetSignature ( const char * newsignature ) [inline]

Change the database signature (first 8 bytes) from 'cbtreedb' to a custom string.

The signature is always 8 bytes long. Longer strings are truncated, shorter ones padded with nulls.

Definition at line 1558 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

uint32_t stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::Size ( ) const [inline]

Returns the number of items in the loaded database.

Definition at line 1681 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

bool stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::Verify ( ) [inline]

Verify all aspects of the loaded database.

Returns:: true if database is ok.

Definition at line 1974 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

bool stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::VerifyBTree ( ) [inline]

Verify B-tree structure in the loaded database.

Returns:: true if database is ok.

Definition at line 1992 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

bool stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::VerifyBTreeChecksum ( ) [inline]

Verify the SHA256 checksum of the B-tree pages in the loaded database.

Returns:: true if database is ok.

Definition at line 2072 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

bool stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::VerifyBTreeNode	(	uint32_t	offset,
		key_type *	minkey,
		key_type *	maxkey,
		uint64_t *	lastoffset
	)			`[inline, protected]`

Internal function: Recursively verify B-tree structure.

Definition at line 2007 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

bool stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::VerifyValueChecksum ( ) [inline]

Verify the SHA256 checksum of value data area in the loaded database.

Returns:: true if database is ok.

Definition at line 2094 of file stx-cbtreedb.h.

Member Data Documentation

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

std::istream* stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::m_istream [protected]

file stream object currently opened.

Definition at line 1433 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

key_compare stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::m_key_less [protected]

key comparison functional

Definition at line 1427 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

PageCache* stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::m_pagecache [protected]

pointer to b-tree page cache to used.

Definition at line 1439 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

unsigned int stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::m_refs [protected]

reference counter

Definition at line 1424 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

SignaturePage stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::m_signature [protected]

signature page read from file

Definition at line 1436 of file stx-cbtreedb.h.

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>

char stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl::m_signaturestr[8] [protected]

signature characters to expect file to begin with.

Definition at line 1430 of file stx-cbtreedb.h.

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

include/stx-cbtreedb.h

stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl Class Reference

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0> class stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

template<typename _Key = uint32_t, typename _Compare = std::less<_Key>, unsigned int _BTreePageSize = 1024, uint32_t _AppVersionId = 0>
class stx::CBTreeDB< _Key, _Compare, _BTreePageSize, _AppVersionId >::ReaderImpl