Polymorphic database. More...

#include <kcpolydb.h>

Classes
class	Cursor
	Cursor to indicate a record. More...
struct	MergeLine
	Front line of a merging list.
struct	SimilarKey
	Key for similarity search.
class	StreamLogger
	Stream logger implementation.
class	StreamMetaTrigger
	Stream meta operation trigger implementation.
Public Types
enum	MergeMode { MSET, MADD, MREPLACE, MAPPEND }
	Merge modes. More...
Public Member Functions
	PolyDB ()
	Default constructor.
virtual	~PolyDB ()
	Destructor.
bool	set_internal_db (BasicDB *db)
	Set the internal database object.
bool	accept (const char kbuf, size_t ksiz, Visitor visitor, bool writable=true)
	Accept a visitor to a record.
bool	accept_bulk (const std::vector< std::string > &keys, Visitor *visitor, bool writable=true)
	Accept a visitor to multiple records at once.
bool	iterate (Visitor visitor, bool writable=true, ProgressChecker checker=NULL)
	Iterate to accept a visitor for each record.
bool	scan_parallel (Visitor visitor, size_t thnum, ProgressChecker checker=NULL)
	Scan each record in parallel.
Error	error () const
	Get the last happened error.
void	set_error (const char file, int32_t line, const char func, Error::Code code, const char *message)
	Set the error information.
void	set_error (Error::Code code, const char *message)
	Set the error information without source code information.
bool	open (const std::string &path=":", uint32_t mode=OWRITER\|OCREATE)
	Open a database file.
bool	close ()
	Close the database file.
bool	synchronize (bool hard=false, FileProcessor proc=NULL, ProgressChecker checker=NULL)
	Synchronize updated contents with the file and the device.
bool	occupy (bool writable=true, FileProcessor *proc=NULL)
	Occupy database by locking and do something meanwhile.
bool	begin_transaction (bool hard=false)
	Begin transaction.
bool	begin_transaction_try (bool hard=false)
	Try to begin transaction.
bool	end_transaction (bool commit=true)
	End transaction.
bool	clear ()
	Remove all records.
int64_t	count ()
	Get the number of records.
int64_t	size ()
	Get the size of the database file.
std::string	path ()
	Get the path of the database file.
bool	status (std::map< std::string, std::string > *strmap)
	Get the miscellaneous status information.
BasicDB *	reveal_inner_db ()
	Reveal the inner database object.
int64_t	match_prefix (const std::string &prefix, std::vector< std::string > strvec, int64_t max=-1, ProgressChecker checker=NULL)
	Get keys matching a prefix string.
int64_t	match_regex (const std::string &regex, std::vector< std::string > strvec, int64_t max=-1, ProgressChecker checker=NULL)
	Get keys matching a regular expression string.
int64_t	match_similar (const std::string &origin, size_t range, bool utf, std::vector< std::string > strvec, int64_t max=-1, ProgressChecker checker=NULL)
	Get keys similar to a string in terms of the levenshtein distance.
bool	merge (BasicDB *srcary, size_t srcnum, MergeMode mode=MSET, ProgressChecker checker=NULL)
	Merge records from other databases.
Cursor *	cursor ()
	Create a cursor object.
void	log (const char file, int32_t line, const char func, Logger::Kind kind, const char *message)
	Write a log message.
bool	tune_logger (Logger *logger, uint32_t kinds=Logger::WARN\|Logger::ERROR)
	Set the internal logger.
bool	tune_meta_trigger (MetaTrigger *trigger)
	Set the internal meta operation trigger.

Detailed Description

Polymorphic database.

Note:: This class is a concrete class to operate an arbitrary database whose type is determined in runtime. This class can be inherited but overwriting methods is forbidden. Before every database operation, it is necessary to call the PolyDB::open method in order to open a database file and connect the database object to it. To avoid data missing or corruption, it is important to close every database file by the PolyDB::close method when the database is no longer in use. It is forbidden for multible database objects in a process to open the same database at the same time. It is forbidden to share a database object with child processes.

Member Enumeration Documentation

enum kyotocabinet::PolyDB::MergeMode

Merge modes.

Enumerator:

MSET	overwrite the existing value
MADD	keep the existing value
MREPLACE	modify the existing record only
MAPPEND	append the new value

Constructor & Destructor Documentation

kyotocabinet::PolyDB::PolyDB ( ) [explicit]

Default constructor.

virtual kyotocabinet::PolyDB::~PolyDB ( ) [virtual]

Destructor.

Note:: If the database is not closed, it is closed implicitly.

Member Function Documentation

bool kyotocabinet::PolyDB::set_internal_db ( BasicDB * db )

Set the internal database object.

Parameters:

db	the internal database object. Its possession is transferred inside and the object is deleted automatically.

Returns:: true on success, or false on failure.

bool kyotocabinet::PolyDB::accept	(	const char *	kbuf,
		size_t	ksiz,
		Visitor *	visitor,
		bool	writable = `true`
	)		`[virtual]`

Accept a visitor to a record.

Parameters:

kbuf	the pointer to the key region.
ksiz	the size of the key region.
visitor	a visitor object.
writable	true for writable operation, or false for read-only operation.

Returns:: true on success, or false on failure.

Note:: The operation for each record is performed atomically and other threads accessing the same record are blocked. To avoid deadlock, any explicit database operation must not be performed in this function.

Implements kyotocabinet::DB.

bool kyotocabinet::PolyDB::accept_bulk	(	const std::vector< std::string > &	keys,
		Visitor *	visitor,
		bool	writable = `true`
	)		`[virtual]`

Accept a visitor to multiple records at once.

Parameters:

keys	specifies a string vector of the keys.
visitor	a visitor object.
writable	true for writable operation, or false for read-only operation.

Returns:: true on success, or false on failure.

Note:: The operations for specified records are performed atomically and other threads accessing the same records are blocked. To avoid deadlock, any explicit database operation must not be performed in this function.

Implements kyotocabinet::BasicDB.

bool kyotocabinet::PolyDB::iterate	(	Visitor *	visitor,
		bool	writable = `true`,
		ProgressChecker *	checker = `NULL`
	)		`[virtual]`

Iterate to accept a visitor for each record.

Parameters:

visitor	a visitor object.
writable	true for writable operation, or false for read-only operation.
checker	a progress checker object. If it is NULL, no checking is performed.

Returns:: true on success, or false on failure.

Note:: The whole iteration is performed atomically and other threads are blocked. To avoid deadlock, any explicit database operation must not be performed in this function.

Implements kyotocabinet::BasicDB.

bool kyotocabinet::PolyDB::scan_parallel	(	Visitor *	visitor,
		size_t	thnum,
		ProgressChecker *	checker = `NULL`
	)		`[virtual]`

Scan each record in parallel.

Parameters:

visitor	a visitor object.
thnum	the number of worker threads.
checker	a progress checker object. If it is NULL, no checking is performed.

Returns:: true on success, or false on failure.

Note:: This function is for reading records and not for updating ones. The return value of the visitor is just ignored. To avoid deadlock, any explicit database operation must not be performed in this function.

Implements kyotocabinet::BasicDB.

Error kyotocabinet::PolyDB::error ( ) const [virtual]

Get the last happened error.

Returns:: the last happened error.

Implements kyotocabinet::BasicDB.

void kyotocabinet::PolyDB::set_error	(	const char *	file,
		int32_t	line,
		const char *	func,
		Error::Code	code,
		const char *	message
	)

Set the error information.

Parameters:

file	the file name of the program source code.
line	the line number of the program source code.
func	the function name of the program source code.
code	an error code.
message	a supplement message.

void kyotocabinet::PolyDB::set_error	(	Error::Code	code,
		const char *	message
	)

Set the error information without source code information.

Parameters:

code	an error code.
message	a supplement message.

bool kyotocabinet::PolyDB::open	(	const std::string &	path = `":"`,
		uint32_t	mode = `OWRITER \| OCREATE`
	)		`[virtual]`

Open a database file.

Parameters:

path the path of a database file. If it is "-", the database will be a prototype hash database. If it is "+", the database will be a prototype tree database. If it is ":", the database will be a stash database. If it is "*", the database will be a cache hash database. If it is "%", the database will be a cache tree database. If its suffix is ".kch", the database will be a file hash database. If its suffix is ".kct", the database will be a file tree database. If its suffix is ".kcd", the database will be a directory hash database. If its suffix is ".kcf", the database will be a directory tree database. If its suffix is ".kcx", the database will be a plain text database. Otherwise, this function fails. Tuning parameters can trail the name, separated by "#". Each parameter is composed of the name and the value, separated by "=". If the "type" parameter is specified, the database type is determined by the value in "-", "+", ":", "*", "%", "kch", "kct", "kcd", kcf", and "kcx". All database types support the logging parameters of "log", "logkinds", and "logpx". The prototype hash database and the prototype tree database do not support any other tuning parameter. The stash database supports "bnum". The cache hash database supports "opts", "bnum", "zcomp", "capcnt", "capsiz", and "zkey". The cache tree database supports all parameters of the cache hash database except for capacity limitation, and supports "psiz", "rcomp", "pccap" in addition. The file hash database supports "apow", "fpow", "opts", "bnum", "msiz", "dfunit", "zcomp", and "zkey". The file tree database supports all parameters of the file hash database and "psiz", "rcomp", "pccap" in addition. The directory hash database supports "opts", "zcomp", and "zkey". The directory tree database supports all parameters of the directory hash database and "psiz", "rcomp", "pccap" in addition. The plain text database does not support any other tuning parameter.

mode the connection mode. PolyDB::OWRITER as a writer, PolyDB::OREADER as a reader. The following may be added to the writer mode by bitwise-or: PolyDB::OCREATE, which means it creates a new database if the file does not exist, PolyDB::OTRUNCATE, which means it creates a new database regardless if the file exists, PolyDB::OAUTOTRAN, which means each updating operation is performed in implicit transaction, PolyDB::OAUTOSYNC, which means each updating operation is followed by implicit synchronization with the file system. The following may be added to both of the reader mode and the writer mode by bitwise-or: PolyDB::ONOLOCK, which means it opens the database file without file locking, PolyDB::OTRYLOCK, which means locking is performed without blocking, PolyDB::ONOREPAIR, which means the database file is not repaired implicitly even if file destruction is detected.

Returns:: true on success, or false on failure.

Note:: The tuning parameter "log" is for the original "tune_logger" and the value specifies the path of the log file, or "-" for the standard output, or "+" for the standard error. "logkinds" specifies kinds of logged messages and the value can be "debug", "info", "warn", or "error". "logpx" specifies the prefix of each log message. "opts" is for "tune_options" and the value can contain "s" for the small option, "l" for the linear option, and "c" for the compress option. "bnum" corresponds to "tune_bucket". "zcomp" is for "tune_compressor" and the value can be "zlib" for the ZLIB raw compressor, "def" for the ZLIB deflate compressor, "gz" for the ZLIB gzip compressor, "lzo" for the LZO compressor, "lzma" for the LZMA compressor, or "arc" for the Arcfour cipher. "zkey" specifies the cipher key of the compressor. "capcnt" is for "cap_count". "capsiz" is for "cap_size". "psiz" is for "tune_page". "rcomp" is for "tune_comparator" and the value can be "lex" for the lexical comparator, "dec" for the decimal comparator, "lexdesc" for the lexical descending comparator, or "decdesc" for the decimal descending comparator. "pccap" is for "tune_page_cache". "apow" is for "tune_alignment". "fpow" is for "tune_fbp". "msiz" is for "tune_map". "dfunit" is for "tune_defrag". Every opened database must be closed by the PolyDB::close method when it is no longer in use. It is not allowed for two or more database objects in the same process to keep their connections to the same database file at the same time.

Implements kyotocabinet::BasicDB.

bool kyotocabinet::PolyDB::close ( ) [virtual]

Close the database file.

Returns:: true on success, or false on failure.

Implements kyotocabinet::BasicDB.

bool kyotocabinet::PolyDB::synchronize	(	bool	hard = `false`,
		FileProcessor *	proc = `NULL`,
		ProgressChecker *	checker = `NULL`
	)		`[virtual]`

Synchronize updated contents with the file and the device.

Parameters:

hard	true for physical synchronization with the device, or false for logical synchronization with the file system.
proc	a postprocessor object. If it is NULL, no postprocessing is performed.
checker	a progress checker object. If it is NULL, no checking is performed.

Returns:: true on success, or false on failure.

Note:: The operation of the postprocessor is performed atomically and other threads accessing the same record are blocked. To avoid deadlock, any explicit database operation must not be performed in this function.

Implements kyotocabinet::BasicDB.

bool kyotocabinet::PolyDB::occupy	(	bool	writable = `true`,
		FileProcessor *	proc = `NULL`
	)		`[virtual]`

Occupy database by locking and do something meanwhile.

Parameters:

writable	true to use writer lock, or false to use reader lock.
proc	a processor object. If it is NULL, no processing is performed.

Returns:: true on success, or false on failure.

Note:: The operation of the processor is performed atomically and other threads accessing the same record are blocked. To avoid deadlock, any explicit database operation must not be performed in this function.

Implements kyotocabinet::BasicDB.

bool kyotocabinet::PolyDB::begin_transaction ( bool hard = false ) [virtual]

Begin transaction.

Parameters:

hard	true for physical synchronization with the device, or false for logical synchronization with the file system.

Returns:: true on success, or false on failure.

Implements kyotocabinet::BasicDB.

bool kyotocabinet::PolyDB::begin_transaction_try ( bool hard = false ) [virtual]

Try to begin transaction.

Parameters:

hard	true for physical synchronization with the device, or false for logical synchronization with the file system.

Returns:: true on success, or false on failure.

Implements kyotocabinet::BasicDB.

bool kyotocabinet::PolyDB::end_transaction ( bool commit = true ) [virtual]

End transaction.

Parameters:

commit true to commit the transaction, or false to abort the transaction.

Returns:: true on success, or false on failure.

Implements kyotocabinet::BasicDB.

bool kyotocabinet::PolyDB::clear ( ) [virtual]

Remove all records.

Returns:: true on success, or false on failure.

Implements kyotocabinet::DB.

int64_t kyotocabinet::PolyDB::count ( ) [virtual]

Get the number of records.

Returns:: the number of records, or -1 on failure.

Implements kyotocabinet::DB.

int64_t kyotocabinet::PolyDB::size ( ) [virtual]

Get the size of the database file.

Returns:: the size of the database file in bytes, or -1 on failure.

Implements kyotocabinet::BasicDB.

std::string kyotocabinet::PolyDB::path ( ) [virtual]

Get the path of the database file.

Returns:: the path of the database file, or an empty string on failure.

Implements kyotocabinet::BasicDB.

bool kyotocabinet::PolyDB::status ( std::map< std::string, std::string > * strmap ) [virtual]

Get the miscellaneous status information.

Parameters:

strmap a string map to contain the result.

Returns:: true on success, or false on failure.

Implements kyotocabinet::BasicDB.

BasicDB* kyotocabinet::PolyDB::reveal_inner_db ( )

Reveal the inner database object.

Returns:: the inner database object, or NULL on failure.

int64_t kyotocabinet::PolyDB::match_prefix	(	const std::string &	prefix,
		std::vector< std::string > *	strvec,
		int64_t	max = `-1`,
		ProgressChecker *	checker = `NULL`
	)

Get keys matching a prefix string.

Parameters:

prefix	the prefix string.
strvec	a string vector to contain the result.
max	the maximum number to retrieve. If it is negative, no limit is specified.
checker	a progress checker object. If it is NULL, no checking is performed.

Returns:: the number of retrieved keys or -1 on failure.

int64_t kyotocabinet::PolyDB::match_regex	(	const std::string &	regex,
		std::vector< std::string > *	strvec,
		int64_t	max = `-1`,
		ProgressChecker *	checker = `NULL`
	)

Get keys matching a regular expression string.

Parameters:

regex	the regular expression string.
strvec	a string vector to contain the result.
max	the maximum number to retrieve. If it is negative, no limit is specified.
checker	a progress checker object. If it is NULL, no checking is performed.

Returns:: the number of retrieved keys or -1 on failure.

int64_t kyotocabinet::PolyDB::match_similar	(	const std::string &	origin,
		size_t	range,
		bool	utf,
		std::vector< std::string > *	strvec,
		int64_t	max = `-1`,
		ProgressChecker *	checker = `NULL`
	)

Get keys similar to a string in terms of the levenshtein distance.

Parameters:

origin	the origin string.
range	the maximum distance of keys to adopt.
utf	flag to treat keys as UTF-8 strings.
strvec	a string vector to contain the result.
max	the maximum number to retrieve. If it is negative, no limit is specified.
checker	a progress checker object. If it is NULL, no checking is performed.

Returns:: the number of retrieved keys or -1 on failure.

bool kyotocabinet::PolyDB::merge	(	BasicDB **	srcary,
		size_t	srcnum,
		MergeMode	mode = `MSET`,
		ProgressChecker *	checker = `NULL`
	)

Merge records from other databases.

Parameters:

srcary	an array of the source detabase objects.
srcnum	the number of the elements of the source array.
mode	the merge mode. PolyDB::MSET to overwrite the existing value, PolyDB::MADD to keep the existing value, PolyDB::MREPLACE to modify the existing record only, PolyDB::MAPPEND to append the new value.
checker	a progress checker object. If it is NULL, no checking is performed.

Returns:: true on success, or false on failure.

Cursor* kyotocabinet::PolyDB::cursor ( ) [virtual]

Create a cursor object.

Returns:: the return value is the created cursor object.

Note:: Because the object of the return value is allocated by the constructor, it should be released with the delete operator when it is no longer in use.

Implements kyotocabinet::BasicDB.

void kyotocabinet::PolyDB::log	(	const char *	file,
		int32_t	line,
		const char *	func,
		Logger::Kind	kind,
		const char *	message
	)

Write a log message.

Parameters:

file	the file name of the program source code.
line	the line number of the program source code.
func	the function name of the program source code.
kind	the kind of the event. Logger::DEBUG for debugging, Logger::INFO for normal information, Logger::WARN for warning, and Logger::ERROR for fatal error.
message	the supplement message.

bool kyotocabinet::PolyDB::tune_logger	(	Logger *	logger,
		uint32_t	kinds = `Logger::WARN \| Logger::ERROR`
	)		`[virtual]`

Set the internal logger.

Parameters:

logger	the logger object.
kinds	kinds of logged messages by bitwise-or: Logger::DEBUG for debugging, Logger::INFO for normal information, Logger::WARN for warning, and Logger::ERROR for fatal error.

Returns:: true on success, or false on failure.

Implements kyotocabinet::BasicDB.

bool kyotocabinet::PolyDB::tune_meta_trigger ( MetaTrigger * trigger ) [virtual]

Set the internal meta operation trigger.

Parameters:

trigger the trigger object.

Returns:: true on success, or false on failure.

Implements kyotocabinet::BasicDB.

Classes

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation