kyotocabinet::BasicDB Class Reference

Basic implementation of database. More...

#include <kcdb.h>

List of all members.

Classes

class  Cursor
 Interface of cursor to indicate a record. More...
class  Error
 Error data. More...
class  FileProcessor
 Interface to process the database file. More...
class  Logger
 Interface to log internal information and errors. More...
class  MetaTrigger
 Interface to trigger meta database operations. More...
class  ProgressChecker
 Interface to check progress status of long process. More...

Public Types

enum  Type {
  TYPEVOID = 0x00, TYPEPHASH = 0x10, TYPEPTREE = 0x11, TYPESTASH = 0x18,
  TYPECACHE = 0x20, TYPEGRASS = 0x21, TYPEHASH = 0x30, TYPETREE = 0x31,
  TYPEDIR = 0x40, TYPEFOREST = 0x41, TYPEMISC = 0x80
}
 

Database types.

More...
enum  OpenMode {
  OREADER = 1 << 0, OWRITER = 1 << 1, OCREATE = 1 << 2, OTRUNCATE = 1 << 3,
  OAUTOTRAN = 1 << 4, OAUTOSYNC = 1 << 5, ONOLOCK = 1 << 6, OTRYLOCK = 1 << 7,
  ONOREPAIR = 1 << 8
}
 

Open modes.

More...

Public Member Functions

virtual ~BasicDB ()
 Destructor.
virtual Error error () const =0
 Get the last happened error.
virtual void set_error (const char *file, int32_t line, const char *func, Error::Code code, const char *message)=0
 Set the error information.
virtual bool open (const std::string &path, uint32_t mode=OWRITER|OCREATE)=0
 Open a database file.
virtual bool close ()=0
 Close the database file.
virtual bool iterate (Visitor *visitor, bool writable=true, ProgressChecker *checker=NULL)=0
 Iterate to accept a visitor for each record.
virtual bool synchronize (bool hard=false, FileProcessor *proc=NULL, ProgressChecker *checker=NULL)=0
 Synchronize updated contents with the file and the device.
bool copy (const std::string &dest, ProgressChecker *checker=NULL)
 Create a copy of the database file.
virtual bool begin_transaction (bool hard=false)=0
 Begin transaction.
virtual bool begin_transaction_try (bool hard=false)=0
 Try to begin transaction.
virtual bool end_transaction (bool commit=true)=0
 End transaction.
virtual int64_t size ()=0
 Get the size of the database file.
virtual std::string path ()=0
 Get the path of the database file.
virtual bool status (std::map< std::string, std::string > *strmap)=0
 Get the miscellaneous status information.
bool set (const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz)
 Set the value of a record.
bool set (const std::string &key, const std::string &value)
 Set the value of a record.
bool add (const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz)
 Add a record.
bool add (const std::string &key, const std::string &value)
 Set the value of a record.
bool replace (const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz)
 Replace the value of a record.
bool replace (const std::string &key, const std::string &value)
 Replace the value of a record.
bool append (const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz)
 Append the value of a record.
bool append (const std::string &key, const std::string &value)
 Set the value of a record.
int64_t increment (const char *kbuf, size_t ksiz, int64_t num)
 Add a number to the numeric value of a record.
int64_t increment (const std::string &key, int64_t num)
 Add a number to the numeric value of a record.
double increment_double (const char *kbuf, size_t ksiz, double num)
 Add a number to the numeric double value of a record.
double increment_double (const std::string &key, double num)
 Add a number to the numeric double value of a record.
bool cas (const char *kbuf, size_t ksiz, const char *ovbuf, size_t ovsiz, const char *nvbuf, size_t nvsiz)
 Perform compare-and-swap.
bool cas (const std::string &key, const std::string &ovalue, const std::string &nvalue)
 Perform compare-and-swap.
bool remove (const char *kbuf, size_t ksiz)
 Remove a record.
bool remove (const std::string &key)
 Remove a record.
char * get (const char *kbuf, size_t ksiz, size_t *sp)
 Retrieve the value of a record.
std::string * get (const std::string &key)
 Retrieve the value of a record.
int32_t get (const char *kbuf, size_t ksiz, char *vbuf, size_t max)
 Retrieve the value of a record.
bool dump_snapshot (std::ostream *dest, ProgressChecker *checker=NULL)
 Dump records into a data stream.
bool dump_snapshot (const std::string &dest, ProgressChecker *checker=NULL)
 Dump records into a file.
bool load_snapshot (std::istream *src, ProgressChecker *checker=NULL)
 Load records from a data stream.
bool load_snapshot (const std::string &src, ProgressChecker *checker=NULL)
 Load records from a file.
virtual Cursorcursor ()=0
 Create a cursor object.
virtual bool tune_logger (Logger *logger, uint32_t kinds=Logger::WARN|Logger::ERROR)=0
 Set the internal logger.
virtual bool tune_meta_trigger (MetaTrigger *trigger)=0
 Set the internal meta operation trigger.

Static Public Member Functions

static const char * typecname (uint32_t type)
 Get the class name of a database type.
static const char * typestring (uint32_t type)
 Get the description string of a database type.

Detailed Description

Basic implementation of database.

Note:
This class is an abstract class to prescribe the interface of file operations and provide mix-in methods. This class can be inherited but overwriting methods is forbidden. Before every database operation, it is necessary to call the BasicDB::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 BasicDB::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

Database types.

Enumerator:
TYPEVOID 

void database

TYPEPHASH 

prototype hash database

TYPEPTREE 

prototype tree database

TYPESTASH 

stash database

TYPECACHE 

cache hash database

TYPEGRASS 

cache tree database

TYPEHASH 

file hash database

TYPETREE 

file tree database

TYPEDIR 

directory hash database

TYPEFOREST 

directory tree database

TYPEMISC 

miscellaneous database

Open modes.

Enumerator:
OREADER 

open as a reader

OWRITER 

open as a writer

OCREATE 

writer creating

OTRUNCATE 

writer truncating

OAUTOTRAN 

auto transaction

OAUTOSYNC 

auto synchronization

ONOLOCK 

open without locking

OTRYLOCK 

lock without blocking

ONOREPAIR 

open without auto repair


Constructor & Destructor Documentation

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

Destructor.

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

Member Function Documentation

virtual Error kyotocabinet::BasicDB::error (  )  const [pure virtual]
virtual void kyotocabinet::BasicDB::set_error ( const char *  file,
int32_t  line,
const char *  func,
Error::Code  code,
const char *  message 
) [pure virtual]

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.
virtual bool kyotocabinet::BasicDB::open ( const std::string &  path,
uint32_t  mode = OWRITER|OCREATE 
) [pure virtual]

Open a database file.

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

Implemented in kyotocabinet::CacheDB, kyotocabinet::DirDB, kyotocabinet::HashDB, kyotocabinet::PlantDB< BASEDB, DBTYPE >, kyotocabinet::PolyDB, kyotocabinet::ProtoDB< STRMAP, DBTYPE >, and kyotocabinet::StashDB.

virtual bool kyotocabinet::BasicDB::close (  )  [pure virtual]
virtual bool kyotocabinet::BasicDB::iterate ( Visitor visitor,
bool  writable = true,
ProgressChecker checker = NULL 
) [pure 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 database operation must not be performed in this function.

Implemented in kyotocabinet::CacheDB, kyotocabinet::DirDB, kyotocabinet::HashDB, kyotocabinet::PlantDB< BASEDB, DBTYPE >, kyotocabinet::PolyDB, kyotocabinet::ProtoDB< STRMAP, DBTYPE >, and kyotocabinet::StashDB.

virtual bool kyotocabinet::BasicDB::synchronize ( bool  hard = false,
FileProcessor proc = NULL,
ProgressChecker checker = NULL 
) [pure 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.

Implemented in kyotocabinet::CacheDB, kyotocabinet::DirDB, kyotocabinet::HashDB, kyotocabinet::PlantDB< BASEDB, DBTYPE >, kyotocabinet::PolyDB, kyotocabinet::ProtoDB< STRMAP, DBTYPE >, and kyotocabinet::StashDB.

bool kyotocabinet::BasicDB::copy ( const std::string &  dest,
ProgressChecker checker = NULL 
)

Create a copy of the database file.

Parameters:
dest the path of the destination file.
checker a progress checker object. If it is NULL, no checking is performed.
Returns:
true on success, or false on failure.
virtual bool kyotocabinet::BasicDB::begin_transaction ( bool  hard = false  )  [pure 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.

Implemented in kyotocabinet::CacheDB, kyotocabinet::DirDB, kyotocabinet::HashDB, kyotocabinet::PlantDB< BASEDB, DBTYPE >, kyotocabinet::PolyDB, kyotocabinet::ProtoDB< STRMAP, DBTYPE >, and kyotocabinet::StashDB.

virtual bool kyotocabinet::BasicDB::begin_transaction_try ( bool  hard = false  )  [pure 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.

Implemented in kyotocabinet::CacheDB, kyotocabinet::DirDB, kyotocabinet::HashDB, kyotocabinet::PlantDB< BASEDB, DBTYPE >, kyotocabinet::PolyDB, kyotocabinet::ProtoDB< STRMAP, DBTYPE >, and kyotocabinet::StashDB.

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

End transaction.

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

Implemented in kyotocabinet::CacheDB, kyotocabinet::DirDB, kyotocabinet::HashDB, kyotocabinet::PlantDB< BASEDB, DBTYPE >, kyotocabinet::PolyDB, kyotocabinet::ProtoDB< STRMAP, DBTYPE >, and kyotocabinet::StashDB.

virtual int64_t kyotocabinet::BasicDB::size (  )  [pure virtual]

Get the size of the database file.

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

Implemented in kyotocabinet::CacheDB, kyotocabinet::DirDB, kyotocabinet::HashDB, kyotocabinet::PlantDB< BASEDB, DBTYPE >, kyotocabinet::PolyDB, kyotocabinet::ProtoDB< STRMAP, DBTYPE >, and kyotocabinet::StashDB.

virtual std::string kyotocabinet::BasicDB::path (  )  [pure virtual]

Get the path of the database file.

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

Implemented in kyotocabinet::CacheDB, kyotocabinet::DirDB, kyotocabinet::HashDB, kyotocabinet::PlantDB< BASEDB, DBTYPE >, kyotocabinet::PolyDB, kyotocabinet::ProtoDB< STRMAP, DBTYPE >, and kyotocabinet::StashDB.

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

Get the miscellaneous status information.

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

Implemented in kyotocabinet::CacheDB, kyotocabinet::DirDB, kyotocabinet::HashDB, kyotocabinet::PlantDB< BASEDB, DBTYPE >, kyotocabinet::PolyDB, kyotocabinet::ProtoDB< STRMAP, DBTYPE >, and kyotocabinet::StashDB.

bool kyotocabinet::BasicDB::set ( const char *  kbuf,
size_t  ksiz,
const char *  vbuf,
size_t  vsiz 
) [virtual]

Set the value of a record.

Parameters:
kbuf the pointer to the key region.
ksiz the size of the key region.
vbuf the pointer to the value region.
vsiz the size of the value region.
Returns:
true on success, or false on failure.
Note:
If no record corresponds to the key, a new record is created. If the corresponding record exists, the value is overwritten.

Implements kyotocabinet::DB.

bool kyotocabinet::BasicDB::set ( const std::string &  key,
const std::string &  value 
) [virtual]

Set the value of a record.

Note:
Equal to the original DB::set method except that the parameters are std::string.

Implements kyotocabinet::DB.

bool kyotocabinet::BasicDB::add ( const char *  kbuf,
size_t  ksiz,
const char *  vbuf,
size_t  vsiz 
) [virtual]

Add a record.

Parameters:
kbuf the pointer to the key region.
ksiz the size of the key region.
vbuf the pointer to the value region.
vsiz the size of the value region.
Returns:
true on success, or false on failure.
Note:
If no record corresponds to the key, a new record is created. If the corresponding record exists, the record is not modified and false is returned.

Implements kyotocabinet::DB.

bool kyotocabinet::BasicDB::add ( const std::string &  key,
const std::string &  value 
) [virtual]

Set the value of a record.

Note:
Equal to the original DB::add method except that the parameters are std::string.

Implements kyotocabinet::DB.

bool kyotocabinet::BasicDB::replace ( const char *  kbuf,
size_t  ksiz,
const char *  vbuf,
size_t  vsiz 
) [virtual]

Replace the value of a record.

Parameters:
kbuf the pointer to the key region.
ksiz the size of the key region.
vbuf the pointer to the value region.
vsiz the size of the value region.
Returns:
true on success, or false on failure.
Note:
If no record corresponds to the key, no new record is created and false is returned. If the corresponding record exists, the value is modified.

Implements kyotocabinet::DB.

bool kyotocabinet::BasicDB::replace ( const std::string &  key,
const std::string &  value 
) [virtual]

Replace the value of a record.

Note:
Equal to the original DB::replace method except that the parameters are std::string.

Implements kyotocabinet::DB.

bool kyotocabinet::BasicDB::append ( const char *  kbuf,
size_t  ksiz,
const char *  vbuf,
size_t  vsiz 
) [virtual]

Append the value of a record.

Parameters:
kbuf the pointer to the key region.
ksiz the size of the key region.
vbuf the pointer to the value region.
vsiz the size of the value region.
Returns:
true on success, or false on failure.
Note:
If no record corresponds to the key, a new record is created. If the corresponding record exists, the given value is appended at the end of the existing value.

Implements kyotocabinet::DB.

bool kyotocabinet::BasicDB::append ( const std::string &  key,
const std::string &  value 
) [virtual]

Set the value of a record.

Note:
Equal to the original DB::append method except that the parameters are std::string.

Implements kyotocabinet::DB.

int64_t kyotocabinet::BasicDB::increment ( const char *  kbuf,
size_t  ksiz,
int64_t  num 
) [virtual]

Add a number to the numeric value of a record.

Parameters:
kbuf the pointer to the key region.
ksiz the size of the key region.
num the additional number.
Returns:
the result value, or INT64_MIN on failure.

Implements kyotocabinet::DB.

int64_t kyotocabinet::BasicDB::increment ( const std::string &  key,
int64_t  num 
) [virtual]

Add a number to the numeric value of a record.

Note:
Equal to the original DB::increment method except that the parameter is std::string.

Implements kyotocabinet::DB.

double kyotocabinet::BasicDB::increment_double ( const char *  kbuf,
size_t  ksiz,
double  num 
) [virtual]

Add a number to the numeric double value of a record.

Parameters:
kbuf the pointer to the key region.
ksiz the size of the key region.
num the additional number.
Returns:
the result value, or Not-a-number on failure.

Implements kyotocabinet::DB.

double kyotocabinet::BasicDB::increment_double ( const std::string &  key,
double  num 
) [virtual]

Add a number to the numeric double value of a record.

Note:
Equal to the original DB::increment_double method except that the parameter is std::string.

Implements kyotocabinet::DB.

bool kyotocabinet::BasicDB::cas ( const char *  kbuf,
size_t  ksiz,
const char *  ovbuf,
size_t  ovsiz,
const char *  nvbuf,
size_t  nvsiz 
) [virtual]

Perform compare-and-swap.

Parameters:
kbuf the pointer to the key region.
ksiz the size of the key region.
ovbuf the pointer to the old value region. NULL means that no record corresponds.
ovsiz the size of the old value region.
nvbuf the pointer to the new value region. NULL means that the record is removed.
nvsiz the size of new old value region.
Returns:
true on success, or false on failure.

Implements kyotocabinet::DB.

bool kyotocabinet::BasicDB::cas ( const std::string &  key,
const std::string &  ovalue,
const std::string &  nvalue 
) [virtual]

Perform compare-and-swap.

Note:
Equal to the original DB::cas method except that the parameters are std::string.

Implements kyotocabinet::DB.

bool kyotocabinet::BasicDB::remove ( const char *  kbuf,
size_t  ksiz 
) [virtual]

Remove a record.

Parameters:
kbuf the pointer to the key region.
ksiz the size of the key region.
Returns:
true on success, or false on failure.
Note:
If no record corresponds to the key, false is returned.

Implements kyotocabinet::DB.

bool kyotocabinet::BasicDB::remove ( const std::string &  key  )  [virtual]

Remove a record.

Note:
Equal to the original DB::remove method except that the parameter is std::string.

Implements kyotocabinet::DB.

char* kyotocabinet::BasicDB::get ( const char *  kbuf,
size_t  ksiz,
size_t *  sp 
) [virtual]

Retrieve the value of a record.

Parameters:
kbuf the pointer to the key region.
ksiz the size of the key region.
sp the pointer to the variable into which the size of the region of the return value is assigned.
Returns:
the pointer to the value region of the corresponding record, or NULL on failure.
Note:
If no record corresponds to the key, NULL is returned. Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a C-style string. Because the region of the return value is allocated with the the new[] operator, it should be released with the delete[] operator when it is no longer in use.

Implements kyotocabinet::DB.

std::string* kyotocabinet::BasicDB::get ( const std::string &  key  )  [virtual]

Retrieve the value of a record.

Note:
Equal to the original DB::get method except that the parameter and the return value are std::string. The return value should be deleted explicitly by the caller.

Implements kyotocabinet::DB.

int32_t kyotocabinet::BasicDB::get ( const char *  kbuf,
size_t  ksiz,
char *  vbuf,
size_t  max 
) [virtual]

Retrieve the value of a record.

Parameters:
kbuf the pointer to the key region.
ksiz the size of the key region.
vbuf the pointer to the buffer into which the value of the corresponding record is written.
max the size of the buffer.
Returns:
the size of the value, or -1 on failure.

Implements kyotocabinet::DB.

bool kyotocabinet::BasicDB::dump_snapshot ( std::ostream *  dest,
ProgressChecker checker = NULL 
)

Dump records into a data stream.

Parameters:
dest the destination stream.
checker a progress checker object. If it is NULL, no checking is performed.
Returns:
true on success, or false on failure.
bool kyotocabinet::BasicDB::dump_snapshot ( const std::string &  dest,
ProgressChecker checker = NULL 
)

Dump records into a file.

Parameters:
dest the path of the destination file.
checker a progress checker object. If it is NULL, no checking is performed.
Returns:
true on success, or false on failure.
bool kyotocabinet::BasicDB::load_snapshot ( std::istream *  src,
ProgressChecker checker = NULL 
)

Load records from a data stream.

Parameters:
src the source stream.
checker a progress checker object. If it is NULL, no checking is performed.
Returns:
true on success, or false on failure.
bool kyotocabinet::BasicDB::load_snapshot ( const std::string &  src,
ProgressChecker checker = NULL 
)

Load records from a file.

Parameters:
src the path of the source file.
checker a progress checker object. If it is NULL, no checking is performed.
Returns:
true on success, or false on failure.
virtual Cursor* kyotocabinet::BasicDB::cursor (  )  [pure 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::DB.

Implemented in kyotocabinet::CacheDB, kyotocabinet::DirDB, kyotocabinet::HashDB, kyotocabinet::PlantDB< BASEDB, DBTYPE >, kyotocabinet::PolyDB, kyotocabinet::ProtoDB< STRMAP, DBTYPE >, and kyotocabinet::StashDB.

virtual bool kyotocabinet::BasicDB::tune_logger ( Logger logger,
uint32_t  kinds = Logger::WARN|Logger::ERROR 
) [pure 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.

Implemented in kyotocabinet::CacheDB, and kyotocabinet::PlantDB< BASEDB, DBTYPE >.

virtual bool kyotocabinet::BasicDB::tune_meta_trigger ( MetaTrigger trigger  )  [pure virtual]

Set the internal meta operation trigger.

Parameters:
trigger the trigger object.
Returns:
true on success, or false on failure.

Implemented in kyotocabinet::CacheDB.

static const char* kyotocabinet::BasicDB::typecname ( uint32_t  type  )  [static]

Get the class name of a database type.

Parameters:
type the database type.
Returns:
the string of the type name.
static const char* kyotocabinet::BasicDB::typestring ( uint32_t  type  )  [static]

Get the description string of a database type.

Parameters:
type the database type.
Returns:
the string of the type name.
Generated on Sun Dec 19 12:53:11 2010 for Kyoto Cabinet by  doxygen 1.6.3