kyotocabinet::HashDB Class Reference

File hash database. More...

#include <kchashdb.h>

List of all members.

Classes
class	Cursor
	Cursor to indicate a record. More...
struct	FreeBlock
	Free block data.
struct	FreeBlockComparator
	Comparator for free blocks.
struct	Record
	Record data.
class	Repeater
	Repeating visitor.
class	ScopedVisitor
	Scoped visitor.
Public Types
enum	Option { TSMALL = 1 << 0, TLINEAR = 1 << 1, TCOMPRESS = 1 << 2 }
	Tuning options. More...
enum	Flag { FOPEN = 1 << 0, FFATAL = 1 << 1 }
	Status flags. More...
Public Member Functions
	HashDB ()
	Default constructor.
virtual	~HashDB ()
	Destructor.
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.
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.
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.
bool	tune_alignment (int8_t apow)
	Set the power of the alignment of record size.
bool	tune_fbp (int8_t fpow)
	Set the power of the capacity of the free block pool.
bool	tune_options (int8_t opts)
	Set the optional features.
bool	tune_buckets (int64_t bnum)
	Set the number of buckets of the hash table.
bool	tune_map (int64_t msiz)
	Set the size of the internal memory-mapped region.
bool	tune_defrag (int64_t dfunit)
	Set the unit step number of auto defragmentation.
bool	tune_compressor (Compressor *comp)
	Set the data compressor.
char *	opaque ()
	Get the opaque data.
bool	synchronize_opaque ()
	Synchronize the opaque data.
bool	defrag (int64_t step=0)
	Perform defragmentation of the file.
uint8_t	flags ()
	Get the status flags.
Protected Member Functions
void	report (const char *file, int32_t line, const char *func, Logger::Kind kind, const char *format,...)
	Report a message for debugging.
void	report_valist (const char *file, int32_t line, const char *func, Logger::Kind kind, const char *format, va_list ap)
	Report a message for debugging with variable number of arguments.
void	report_binary (const char *file, int32_t line, const char *func, Logger::Kind kind, const char *name, const char *buf, size_t size)
	Report the content of a binary buffer for debugging.
void	trigger_meta (MetaTrigger::Kind kind, const char *message)
	Trigger a meta database operation.
bool	tune_type (int8_t type)
	Set the database type.
uint8_t	libver ()
	Get the library version.
uint8_t	librev ()
	Get the library revision.
uint8_t	fmtver ()
	Get the format version.
uint8_t	chksum ()
	Get the module checksum.
uint8_t	type ()
	Get the database type.
uint8_t	apow ()
	Get the alignment power.
uint8_t	fpow ()
	Get the free block pool power.
uint8_t	opts ()
	Get the options.
int64_t	bnum ()
	Get the bucket number.
int64_t	msiz ()
	Get the size of the internal memory-mapped region.
int64_t	dfunit ()
	Get the unit step number of auto defragmentation.
Compressor *	comp ()
	Get the data compressor.
bool	recovered ()
	Check whether the database was recovered or not.
bool	reorganized ()
	Check whether the database was reorganized or not.
Friends
class	PlantDB< HashDB, BasicDB::TYPETREE >

---

Detailed Description

File hash database.

Note:

This class is a concrete class to operate a hash database on a file. This class can be inherited but overwriting methods is forbidden. Before every database operation, it is necessary to call the HashDB::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 HashDB::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::HashDB::Option

Tuning options.

Enumerator:

TSMALL	use 32-bit addressing
TLINEAR	use linear collision chaining
TCOMPRESS	compress each record

enum kyotocabinet::HashDB::Flag

Status flags.

Enumerator:

FOPEN	whether opened
FFATAL	whether with fatal error

---

Constructor & Destructor Documentation

kyotocabinet::HashDB::HashDB

(

)

[explicit]

Default constructor.

virtual kyotocabinet::HashDB::~HashDB

(

)

[virtual]

Destructor.

Note:

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

---

Member Function Documentation

bool kyotocabinet::HashDB::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::HashDB::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::HashDB::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::HashDB::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::HashDB::error

(

)

const [virtual]

Get the last happened error.

Returns:

the last happened error.

Implements kyotocabinet::BasicDB.

void kyotocabinet::HashDB::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.

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

Open a database file.

Parameters:

path

the path of a database file.

mode

the connection mode. HashDB::OWRITER as a writer, HashDB::OREADER as a reader. The following may be added to the writer mode by bitwise-or: HashDB::OCREATE, which means it creates a new database if the file does not exist, HashDB::OTRUNCATE, which means it creates a new database regardless if the file exists, HashDB::OAUTOTRAN, which means each updating operation is performed in implicit transaction, HashDB::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: HashDB::ONOLOCK, which means it opens the database file without file locking, HashDB::OTRYLOCK, which means locking is performed without blocking, HashDB::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:

Every opened database must be closed by the HashDB::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::HashDB::close

(

)

[virtual]

Close the database file.

Returns:

true on success, or false on failure.

Implements kyotocabinet::BasicDB.

bool kyotocabinet::HashDB::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::HashDB::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::HashDB::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::HashDB::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::HashDB::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::HashDB::clear

(

)

[virtual]

Remove all records.

Returns:

true on success, or false on failure.

Implements kyotocabinet::DB.

int64_t kyotocabinet::HashDB::count

(

)

[virtual]

Get the number of records.

Returns:

the number of records, or -1 on failure.

Implements kyotocabinet::DB.

int64_t kyotocabinet::HashDB::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::HashDB::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::HashDB::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.

Cursor* kyotocabinet::HashDB::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::HashDB::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::HashDB::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::HashDB::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.

bool kyotocabinet::HashDB::tune_alignment

(

int8_t

apow

)

Set the power of the alignment of record size.

Parameters:

apow	the power of the alignment of record size.

Returns:

true on success, or false on failure.

bool kyotocabinet::HashDB::tune_fbp

(

int8_t

fpow

)

Set the power of the capacity of the free block pool.

Parameters:

fpow	the power of the capacity of the free block pool.

Returns:

true on success, or false on failure.

bool kyotocabinet::HashDB::tune_options

(

int8_t

opts

)

Set the optional features.

Parameters:

opts	the optional features by bitwise-or: HashDB::TSMALL to use 32-bit addressing, HashDB::TLINEAR to use linear collision chaining, HashDB::TCOMPRESS to compress each record.

Returns:

true on success, or false on failure.

bool kyotocabinet::HashDB::tune_buckets

(

int64_t

bnum

)

Set the number of buckets of the hash table.

Parameters:

bnum	the number of buckets of the hash table.

Returns:

true on success, or false on failure.

bool kyotocabinet::HashDB::tune_map

(

int64_t

msiz

)

Set the size of the internal memory-mapped region.

Parameters:

msiz	the size of the internal memory-mapped region.

Returns:

true on success, or false on failure.

bool kyotocabinet::HashDB::tune_defrag

(

int64_t

dfunit

)

Set the unit step number of auto defragmentation.

Parameters:

dfunit

the unit step number of auto defragmentation.

Returns:

true on success, or false on failure.

bool kyotocabinet::HashDB::tune_compressor

(

Compressor *

comp

)

Set the data compressor.

Parameters:

comp	the data compressor object.

Returns:

true on success, or false on failure.

char* kyotocabinet::HashDB::opaque

(

)

Get the opaque data.

Returns:

the pointer to the opaque data region, whose size is 16 bytes.

bool kyotocabinet::HashDB::synchronize_opaque

(

)

Synchronize the opaque data.

Returns:

true on success, or false on failure.

bool kyotocabinet::HashDB::defrag

(

int64_t

step = 0

)

Perform defragmentation of the file.

Parameters:

step	the number of steps. If it is not more than 0, the whole region is defraged.

Returns:

true on success, or false on failure.

uint8_t kyotocabinet::HashDB::flags

(

)

Get the status flags.

Returns:

the status flags, or 0 on failure.

void kyotocabinet::HashDB::report	(	const char *	file,
		int32_t	line,
		const char *	func,
		Logger::Kind	kind,
		const char *	format,
			...
	)		[protected]

Report a message for debugging.

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.
format	the printf-like format string.
...	used according to the format string.

void kyotocabinet::HashDB::report_valist	(	const char *	file,
		int32_t	line,
		const char *	func,
		Logger::Kind	kind,
		const char *	format,
		va_list	ap
	)		[protected]

Report a message for debugging with variable number of arguments.

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.
format	the printf-like format string.
ap	used according to the format string.

void kyotocabinet::HashDB::report_binary	(	const char *	file,
		int32_t	line,
		const char *	func,
		Logger::Kind	kind,
		const char *	name,
		const char *	buf,
		size_t	size
	)		[protected]

Report the content of a binary buffer for debugging.

Parameters:

file	the file name of the epicenter.
line	the line number of the epicenter.
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.
name	the name of the information.
buf	the binary buffer.
size	the size of the binary buffer

void kyotocabinet::HashDB::trigger_meta	(	MetaTrigger::Kind	kind,
		const char *	message
	)		[protected]

Trigger a meta database operation.

Parameters:

kind

the kind of the event. MetaTrigger::OPEN for opening, MetaTrigger::CLOSE for closing, MetaTrigger::CLEAR for clearing, MetaTrigger::ITERATE for iteration, MetaTrigger::SYNCHRONIZE for synchronization, MetaTrigger::BEGINTRAN for beginning transaction, MetaTrigger::COMMITTRAN for committing transaction, MetaTrigger::ABORTTRAN for aborting transaction, and MetaTrigger::MISC for miscellaneous operations.

message

the supplement message.

bool kyotocabinet::HashDB::tune_type

(

int8_t

type

)

[protected]

Set the database type.

Parameters:

type	the database type.

Returns:

true on success, or false on failure.

uint8_t kyotocabinet::HashDB::libver

(

)

[protected]

Get the library version.

Returns:

the library version, or 0 on failure.

uint8_t kyotocabinet::HashDB::librev

(

)

[protected]

Get the library revision.

Returns:

the library revision, or 0 on failure.

uint8_t kyotocabinet::HashDB::fmtver

(

)

[protected]

Get the format version.

Returns:

the format version, or 0 on failure.

uint8_t kyotocabinet::HashDB::chksum

(

)

[protected]

Get the module checksum.

Returns:

the module checksum, or 0 on failure.

uint8_t kyotocabinet::HashDB::type

(

)

[protected]

Get the database type.

Returns:

the database type, or 0 on failure.

uint8_t kyotocabinet::HashDB::apow

(

)

[protected]

Get the alignment power.

Returns:

the alignment power, or 0 on failure.

uint8_t kyotocabinet::HashDB::fpow

(

)

[protected]

Get the free block pool power.

Returns:

the free block pool power, or 0 on failure.

uint8_t kyotocabinet::HashDB::opts

(

)

[protected]

Get the options.

Returns:

the options, or 0 on failure.

int64_t kyotocabinet::HashDB::bnum

(

)

[protected]

Get the bucket number.

Returns:

the bucket number, or 0 on failure.

int64_t kyotocabinet::HashDB::msiz

(

)

[protected]

Get the size of the internal memory-mapped region.

Returns:

the size of the internal memory-mapped region, or 0 on failure.

int64_t kyotocabinet::HashDB::dfunit

(

)

[protected]

Get the unit step number of auto defragmentation.

Returns:

the unit step number of auto defragmentation, or 0 on failure.

Compressor* kyotocabinet::HashDB::comp

(

)

[protected]

Get the data compressor.

Returns:

the data compressor, or NULL on failure.

bool kyotocabinet::HashDB::recovered

(

)

[protected]

Check whether the database was recovered or not.

Returns:

true if recovered, or false if not.

bool kyotocabinet::HashDB::reorganized

(

)

[protected]

Check whether the database was reorganized or not.

Returns:

true if reorganized, or false if not.