Kyoto Cabinet
Classes | Public Member Functions | Protected Member Functions
kyotocabinet::StashDB Class Reference

Economical on-memory hash database. More...

#include <kcstashdb.h>

List of all members.

Classes

class  Cursor
 Cursor to indicate a record. More...
struct  Record
 Record data.
class  Remover
 Removing visitor.
class  Repeater
 Repeating visitor.
class  ScopedVisitor
 Scoped visitor.
class  Setter
 Setting visitor.
struct  TranLog
 Transaction log.

Public Member Functions

 StashDB ()
 Default constructor.
 ~StashDB ()
 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.
Cursorcursor ()
 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_buckets (int64_t bnum)
 Set the number of buckets of the hash table.
char * opaque ()
 Get the opaque data.
bool synchronize_opaque ()
 Synchronize the opaque data.

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.

Detailed Description

Economical on-memory hash database.

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

Constructor & Destructor Documentation

Default constructor.

Destructor.

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

Member Function Documentation

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

Accept a visitor to a record.

Parameters:
kbufthe pointer to the key region.
ksizthe size of the key region.
visitora visitor object.
writabletrue 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::StashDB::accept_bulk ( const std::vector< std::string > &  keys,
Visitor visitor,
bool  writable = true 
) [virtual]

Accept a visitor to multiple records at once.

Parameters:
keysspecifies a string vector of the keys.
visitora visitor object.
writabletrue 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::StashDB::iterate ( Visitor visitor,
bool  writable = true,
ProgressChecker checker = NULL 
) [virtual]

Iterate to accept a visitor for each record.

Parameters:
visitora visitor object.
writabletrue for writable operation, or false for read-only operation.
checkera 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::StashDB::scan_parallel ( Visitor visitor,
size_t  thnum,
ProgressChecker checker = NULL 
) [virtual]

Scan each record in parallel.

Parameters:
visitora visitor object.
thnumthe number of worker threads.
checkera 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::StashDB::error ( ) const [virtual]

Get the last happened error.

Returns:
the last happened error.

Implements kyotocabinet::BasicDB.

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

Set the error information.

Parameters:
filethe file name of the program source code.
linethe line number of the program source code.
functhe function name of the program source code.
codean error code.
messagea supplement message.
bool kyotocabinet::StashDB::open ( const std::string &  path,
uint32_t  mode = OWRITER | OCREATE 
) [virtual]

Open a database file.

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

Close the database file.

Returns:
true on success, or false on failure.

Implements kyotocabinet::BasicDB.

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

Synchronize updated contents with the file and the device.

Parameters:
hardtrue for physical synchronization with the device, or false for logical synchronization with the file system.
proca postprocessor object. If it is NULL, no postprocessing is performed.
checkera 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::StashDB::occupy ( bool  writable = true,
FileProcessor proc = NULL 
) [virtual]

Occupy database by locking and do something meanwhile.

Parameters:
writabletrue to use writer lock, or false to use reader lock.
proca 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::StashDB::begin_transaction ( bool  hard = false) [virtual]

Begin transaction.

Parameters:
hardtrue 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::StashDB::begin_transaction_try ( bool  hard = false) [virtual]

Try to begin transaction.

Parameters:
hardtrue 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::StashDB::end_transaction ( bool  commit = true) [virtual]

End transaction.

Parameters:
committrue to commit the transaction, or false to abort the transaction.
Returns:
true on success, or false on failure.

Implements kyotocabinet::BasicDB.

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

Remove all records.

Returns:
true on success, or false on failure.

Implements kyotocabinet::DB.

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

Get the number of records.

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

Implements kyotocabinet::DB.

int64_t kyotocabinet::StashDB::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::StashDB::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::StashDB::status ( std::map< std::string, std::string > *  strmap) [virtual]

Get the miscellaneous status information.

Parameters:
strmapa string map to contain the result.
Returns:
true on success, or false on failure.

Implements kyotocabinet::BasicDB.

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::StashDB::log ( const char *  file,
int32_t  line,
const char *  func,
Logger::Kind  kind,
const char *  message 
)

Write a log message.

Parameters:
filethe file name of the program source code.
linethe line number of the program source code.
functhe function name of the program source code.
kindthe kind of the event. Logger::DEBUG for debugging, Logger::INFO for normal information, Logger::WARN for warning, and Logger::ERROR for fatal error.
messagethe supplement message.
bool kyotocabinet::StashDB::tune_logger ( Logger *  logger,
uint32_t  kinds = Logger::WARN | Logger::ERROR 
)

Set the internal logger.

Parameters:
loggerthe logger object.
kindskinds 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.
bool kyotocabinet::StashDB::tune_meta_trigger ( MetaTrigger *  trigger)

Set the internal meta operation trigger.

Parameters:
triggerthe trigger object.
Returns:
true on success, or false on failure.
bool kyotocabinet::StashDB::tune_buckets ( int64_t  bnum)

Set the number of buckets of the hash table.

Parameters:
bnumthe number of buckets of the hash table.
Returns:
true on success, or false on failure.

Get the opaque data.

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

Synchronize the opaque data.

Returns:
true on success, or false on failure.
void kyotocabinet::StashDB::report ( const char *  file,
int32_t  line,
const char *  func,
Logger::Kind  kind,
const char *  format,
  ... 
) [protected]

Report a message for debugging.

Parameters:
filethe file name of the program source code.
linethe line number of the program source code.
functhe function name of the program source code.
kindthe kind of the event. Logger::DEBUG for debugging, Logger::INFO for normal information, Logger::WARN for warning, and Logger::ERROR for fatal error.
formatthe printf-like format string.
...used according to the format string.
void kyotocabinet::StashDB::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:
filethe file name of the program source code.
linethe line number of the program source code.
functhe function name of the program source code.
kindthe kind of the event. Logger::DEBUG for debugging, Logger::INFO for normal information, Logger::WARN for warning, and Logger::ERROR for fatal error.
formatthe printf-like format string.
apused according to the format string.
void kyotocabinet::StashDB::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:
filethe file name of the epicenter.
linethe line number of the epicenter.
functhe function name of the program source code.
kindthe kind of the event. Logger::DEBUG for debugging, Logger::INFO for normal information, Logger::WARN for warning, and Logger::ERROR for fatal error.
namethe name of the information.
bufthe binary buffer.
sizethe size of the binary buffer
void kyotocabinet::StashDB::trigger_meta ( MetaTrigger::Kind  kind,
const char *  message 
) [protected]

Trigger a meta database operation.

Parameters:
kindthe 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.
messagethe supplement message.