Tkrzw
Classes | Public Member Functions | List of all members
tkrzw::DBM Class Referenceabstract

Interface of database manager. More...

#include <tkrzw_dbm.h>

Classes

class  FileProcessor
 Interface of processor for a record. More...
 
class  FileProcessorCopyFile
 File processor to implement DBM::CopyFile. More...
 
class  Iterator
 Interface of iterator for each record. More...
 
class  RecordProcessor
 Interface of processor for a record. More...
 
class  RecordProcessorAppend
 Record processor to implement DBM::Append. More...
 
class  RecordProcessorCompareExchange
 Record processor to implement DBM::CompareExchange. More...
 
class  RecordProcessorExport
 Record processor to implement DBM::Export. More...
 
class  RecordProcessorGet
 Record processor to implement DBM::Get. More...
 
class  RecordProcessorIncrement
 Record processor to implement DBM::Increment. More...
 
class  RecordProcessorIteratorGet
 Record processor to implement DBM::Iterator::Get. More...
 
class  RecordProcessorIteratorRemove
 Record processor to implement DBM::Iterator::Remove. More...
 
class  RecordProcessorIteratorSet
 Record processor to implement DBM::Iterator::Set. More...
 
class  RecordProcessorRemove
 Record processor to implement DBM::Remove. More...
 
class  RecordProcessorSet
 Record processor to implement DBM::Set. More...
 

Public Member Functions

virtual ~DBM ()=default
 Destructor. More...
 
virtual Status Open (const std::string &path, bool writable, int32_t options=File::OPEN_DEFAULT)=0
 Opens a database file. More...
 
virtual Status Close ()=0
 Closes the database file. More...
 
virtual Status Process (std::string_view key, RecordProcessor *proc, bool writable)=0
 Processes a record with a processor. More...
 
virtual Status Get (std::string_view key, std::string *value=nullptr)
 Gets the value of a record of a key. More...
 
virtual std::string GetSimple (std::string_view key, std::string_view default_value="")
 Gets the value of a record of a key, in a simple way. More...
 
virtual std::map< std::string, std::string > GetMulti (const std::initializer_list< std::string > &keys)
 Gets the values of multiple records of keys. More...
 
virtual std::map< std::string, std::string > GetMulti (const std::vector< std::string > &keys)
 Gets the values of multiple records of keys, with a vector. More...
 
virtual Status Set (std::string_view key, std::string_view value, bool overwrite=true)
 Sets a record of a key and a value. More...
 
virtual Status SetMulti (const std::initializer_list< std::pair< std::string, std::string >> &records, bool overwrite=true)
 Sets multiple records. More...
 
virtual Status SetMulti (const std::map< std::string, std::string > &records, bool overwrite=true)
 Sets multiple records, with a map of strings. More...
 
virtual Status Remove (std::string_view key)
 Removes a record of a key. More...
 
virtual Status Append (std::string_view key, std::string_view value, std::string_view delim="")
 Appends data at the end of a record of a key. More...
 
virtual Status CompareExchange (std::string_view key, std::string_view expected, std::string_view desired, std::string *actual=nullptr)
 Compares the value of a record and exchanges if the condition meets. More...
 
virtual Status Increment (std::string_view key, int64_t increment=1, int64_t *current=nullptr, int64_t initial=0)
 Increments the numeric value of a record. More...
 
int64_t IncrementSimple (std::string_view key, int64_t increment=1, int64_t initial=0)
 Increments the numeric value of a record, in a simple way. More...
 
virtual Status ProcessEach (RecordProcessor *proc, bool writable)=0
 Processes each and every record in the database with a processor. More...
 
virtual Status Count (int64_t *count)=0
 Gets the number of records. More...
 
virtual int64_t CountSimple ()
 Gets the number of records, in a simple way. More...
 
virtual Status GetFileSize (int64_t *size)=0
 Gets the current file size of the database. More...
 
virtual int64_t GetFileSizeSimple ()
 Gets the current file size of the database, in a simple way. More...
 
virtual Status GetFilePath (std::string *path)=0
 Gets the path of the database file. More...
 
virtual std::string GetFilePathSimple ()
 Gets the path of the database file, in a simple way. More...
 
virtual Status Clear ()=0
 Removes all records. More...
 
virtual Status Rebuild ()=0
 Rebuilds the entire database. More...
 
virtual Status ShouldBeRebuilt (bool *tobe)=0
 Checks whether the database should be rebuilt. More...
 
virtual bool ShouldBeRebuiltSimple ()
 Checks whether the database should be rebuilt, in a simple way. More...
 
virtual Status Synchronize (bool hard, FileProcessor *proc=nullptr)=0
 Synchronizes the content of the database to the file system. More...
 
virtual Status CopyFile (const std::string &dest_path)
 Copies the content of the database file to another file. More...
 
virtual Status Export (DBM *dbm)
 Exports all records to another database. More...
 
virtual std::vector< std::pair< std::string, std::string > > Inspect ()=0
 Inspects the database. More...
 
virtual bool IsOpen () const =0
 Checks whether the database is open. More...
 
virtual bool IsWritable () const =0
 Checks whether the database is writable. More...
 
virtual bool IsHealthy () const =0
 Checks whether the database condition is healthy. More...
 
virtual bool IsOrdered () const =0
 Checks whether ordered operations are supported. More...
 
virtual std::unique_ptr< IteratorMakeIterator ()=0
 Makes an iterator for each record. More...
 
virtual std::unique_ptr< DBMMakeDBM () const =0
 Make a new DBM object of the same concrete class. More...
 

Detailed Description

Interface of database manager.

Constructor & Destructor Documentation

◆ ~DBM()

virtual tkrzw::DBM::~DBM ( )
virtualdefault

Destructor.

Member Function Documentation

◆ Open()

virtual Status tkrzw::DBM::Open ( const std::string &  path,
bool  writable,
int32_t  options = File::OPEN_DEFAULT 
)
pure virtual

Opens a database file.

Parameters
pathA path of the file.
writableIf true, the file is writable. If false, it is read-only.
optionsBit-sum options for opening the file.
Returns
The result status.

Implemented in tkrzw::TreeDBM, tkrzw::TinyDBM, tkrzw::StdTreeDBM, tkrzw::StdHashDBM, tkrzw::SkipDBM, tkrzw::ShardDBM, tkrzw::PolyDBM, tkrzw::HashDBM, tkrzw::CacheDBM, and tkrzw::BabyDBM.

◆ Close()

virtual Status tkrzw::DBM::Close ( )
pure virtual

◆ Process()

virtual Status tkrzw::DBM::Process ( std::string_view  key,
RecordProcessor proc,
bool  writable 
)
pure virtual

Processes a record with a processor.

Parameters
keyThe key of the record.
procThe pointer to the processor object.
writableTrue if the processor can edit the record.
Returns
The result status.

If the specified record exists, the ProcessFull of the processor is called. Otherwise, the ProcessEmpty of the processor is called.

Implemented in tkrzw::TreeDBM, tkrzw::TinyDBM, tkrzw::StdTreeDBM, tkrzw::StdHashDBM, tkrzw::SkipDBM, tkrzw::ShardDBM, tkrzw::PolyDBM, tkrzw::HashDBM, tkrzw::CacheDBM, and tkrzw::BabyDBM.

◆ Get()

virtual Status tkrzw::DBM::Get ( std::string_view  key,
std::string *  value = nullptr 
)
virtual

Gets the value of a record of a key.

Parameters
keyThe key of the record.
valueThe pointer to a string object to contain the result value. If it is nullptr, the value data is ignored.
Returns
The result status.

Reimplemented in tkrzw::ShardDBM, and tkrzw::PolyDBM.

◆ GetSimple()

virtual std::string tkrzw::DBM::GetSimple ( std::string_view  key,
std::string_view  default_value = "" 
)
virtual

Gets the value of a record of a key, in a simple way.

Parameters
keyThe key of the record.
default_valueThe value to be returned on failure.
Returns
The value of the matching record on success, or the default value on failure.

◆ GetMulti() [1/2]

virtual std::map<std::string, std::string> tkrzw::DBM::GetMulti ( const std::initializer_list< std::string > &  keys)
virtual

Gets the values of multiple records of keys.

Parameters
keysThe keys of records to retrieve.
Returns
A map of retrieved records. Keys which don't match existing records are ignored.

◆ GetMulti() [2/2]

virtual std::map<std::string, std::string> tkrzw::DBM::GetMulti ( const std::vector< std::string > &  keys)
virtual

Gets the values of multiple records of keys, with a vector.

Parameters
keysThe keys of records to retrieve.
Returns
A map of retrieved records. Keys which don't match existing records are ignored.

◆ Set()

virtual Status tkrzw::DBM::Set ( std::string_view  key,
std::string_view  value,
bool  overwrite = true 
)
virtual

Sets a record of a key and a value.

Parameters
keyThe key of the record.
valueThe value of the record.
overwriteWhether to overwrite the existing value if there's a record with the same key. If true, the existing value is overwritten by the new value. If false, the operation is given up and an error status is returned.
Returns
The result status.

Reimplemented in tkrzw::SkipDBM, tkrzw::ShardDBM, and tkrzw::PolyDBM.

◆ SetMulti() [1/2]

virtual Status tkrzw::DBM::SetMulti ( const std::initializer_list< std::pair< std::string, std::string >> &  records,
bool  overwrite = true 
)
virtual

Sets multiple records.

Parameters
recordsThe records to store.
overwriteWhether to overwrite the existing value if there's a record with the same key. If true, the existing value is overwritten by the new value. If false, the operation is given up and an error status is returned.
Returns
The result status.

◆ SetMulti() [2/2]

virtual Status tkrzw::DBM::SetMulti ( const std::map< std::string, std::string > &  records,
bool  overwrite = true 
)
virtual

Sets multiple records, with a map of strings.

Parameters
recordsThe records to store.
overwriteWhether to overwrite the existing value if there's a record with the same key. If true, the existing value is overwritten by the new value. If false, the operation is given up and an error status is returned.
Returns
The result status.

◆ Remove()

virtual Status tkrzw::DBM::Remove ( std::string_view  key)
virtual

Removes a record of a key.

Parameters
keyThe key of the record.
Returns
The result status.

Reimplemented in tkrzw::SkipDBM, tkrzw::ShardDBM, and tkrzw::PolyDBM.

◆ Append()

virtual Status tkrzw::DBM::Append ( std::string_view  key,
std::string_view  value,
std::string_view  delim = "" 
)
virtual

Appends data at the end of a record of a key.

Parameters
keyThe key of the record.
valueThe value to append.
delimThe delimiter to put after the existing record.
Returns
The result status.

If there's no existing record, the value is set without the delimiter.

Reimplemented in tkrzw::TinyDBM, tkrzw::ShardDBM, tkrzw::PolyDBM, and tkrzw::BabyDBM.

◆ CompareExchange()

virtual Status tkrzw::DBM::CompareExchange ( std::string_view  key,
std::string_view  expected,
std::string_view  desired,
std::string *  actual = nullptr 
)
virtual

Compares the value of a record and exchanges if the condition meets.

Parameters
keyThe key of the record.
expectedThe expected value.
desiredThe desired value. If the data is nullptr, the record is to be removed.
actualThe pointer to a string object to contain the result value. If it is nullptr, it is ignored.
Returns
The result status.

If the record doesn't exist, NOT_FOUND_ERROR is returned. If the existing value is different from the expected value, DUPLICATION_ERROR is returned. Otherwise, the desired value is set.

◆ Increment()

virtual Status tkrzw::DBM::Increment ( std::string_view  key,
int64_t  increment = 1,
int64_t *  current = nullptr,
int64_t  initial = 0 
)
virtual

Increments the numeric value of a record.

Parameters
keyThe key of the record.
incrementThe incremental value. If it is INT64MIN, the current value is not changed and a new record is not created.
currentThe pointer to an integer to contain the current value. If it is nullptr, it is ignored.
initialThe initial value.
Returns
The result status.

The record value is stored as an 8-byte big-endian integer. Negative is also supported.

◆ IncrementSimple()

int64_t tkrzw::DBM::IncrementSimple ( std::string_view  key,
int64_t  increment = 1,
int64_t  initial = 0 
)

Increments the numeric value of a record, in a simple way.

Parameters
keyThe key of the record.
incrementThe incremental value.
initialThe initial value.
Returns
The current value or INT64MIN on failure.

The record value is treated as a decimal integer. Negative is also supported.

◆ ProcessEach()

virtual Status tkrzw::DBM::ProcessEach ( RecordProcessor proc,
bool  writable 
)
pure virtual

Processes each and every record in the database with a processor.

Parameters
procThe pointer to the processor object.
writableTrue if the processor can edit the record.
Returns
The result status.

The ProcessFull of the processor is called repeatedly for each record. The ProcessEmpty of the processor is called once before the iteration and once after the iteration.

Implemented in tkrzw::TreeDBM, tkrzw::TinyDBM, tkrzw::StdTreeDBM, tkrzw::StdHashDBM, tkrzw::SkipDBM, tkrzw::ShardDBM, tkrzw::PolyDBM, tkrzw::HashDBM, tkrzw::CacheDBM, and tkrzw::BabyDBM.

◆ Count()

virtual Status tkrzw::DBM::Count ( int64_t *  count)
pure virtual

Gets the number of records.

Parameters
countThe pointer to an integer object to contain the result count.
Returns
The result status.

Implemented in tkrzw::TreeDBM, tkrzw::TinyDBM, tkrzw::StdTreeDBM, tkrzw::StdHashDBM, tkrzw::SkipDBM, tkrzw::ShardDBM, tkrzw::PolyDBM, tkrzw::HashDBM, tkrzw::CacheDBM, and tkrzw::BabyDBM.

◆ CountSimple()

virtual int64_t tkrzw::DBM::CountSimple ( )
virtual

Gets the number of records, in a simple way.

Returns
The number of records on success, or -1 on failure.

◆ GetFileSize()

virtual Status tkrzw::DBM::GetFileSize ( int64_t *  size)
pure virtual

Gets the current file size of the database.

Parameters
sizeThe pointer to an integer object to contain the result size.
Returns
The result status.

Implemented in tkrzw::TreeDBM, tkrzw::TinyDBM, tkrzw::StdTreeDBM, tkrzw::StdHashDBM, tkrzw::SkipDBM, tkrzw::ShardDBM, tkrzw::PolyDBM, tkrzw::HashDBM, tkrzw::CacheDBM, and tkrzw::BabyDBM.

◆ GetFileSizeSimple()

virtual int64_t tkrzw::DBM::GetFileSizeSimple ( )
virtual

Gets the current file size of the database, in a simple way.

Returns
The current file size of the database, or -1 on failure.

◆ GetFilePath()

virtual Status tkrzw::DBM::GetFilePath ( std::string *  path)
pure virtual

Gets the path of the database file.

Parameters
pathThe pointer to a string object to contain the result path.
Returns
The result status.

Implemented in tkrzw::TreeDBM, tkrzw::TinyDBM, tkrzw::StdTreeDBM, tkrzw::StdHashDBM, tkrzw::SkipDBM, tkrzw::ShardDBM, tkrzw::PolyDBM, tkrzw::HashDBM, tkrzw::CacheDBM, and tkrzw::BabyDBM.

◆ GetFilePathSimple()

virtual std::string tkrzw::DBM::GetFilePathSimple ( )
virtual

Gets the path of the database file, in a simple way.

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

◆ Clear()

virtual Status tkrzw::DBM::Clear ( )
pure virtual

◆ Rebuild()

virtual Status tkrzw::DBM::Rebuild ( )
pure virtual

◆ ShouldBeRebuilt()

virtual Status tkrzw::DBM::ShouldBeRebuilt ( bool *  tobe)
pure virtual

Checks whether the database should be rebuilt.

Parameters
tobeThe pointer to a boolean object to contain the result decision.
Returns
The result status.

Implemented in tkrzw::TreeDBM, tkrzw::TinyDBM, tkrzw::StdTreeDBM, tkrzw::StdHashDBM, tkrzw::SkipDBM, tkrzw::ShardDBM, tkrzw::PolyDBM, tkrzw::HashDBM, tkrzw::CacheDBM, and tkrzw::BabyDBM.

◆ ShouldBeRebuiltSimple()

virtual bool tkrzw::DBM::ShouldBeRebuiltSimple ( )
virtual

Checks whether the database should be rebuilt, in a simple way.

Returns
True if the database should be rebuilt or false if not or on failure.

◆ Synchronize()

virtual Status tkrzw::DBM::Synchronize ( bool  hard,
FileProcessor proc = nullptr 
)
pure virtual

Synchronizes the content of the database to the file system.

Parameters
hardTrue to do physical synchronization with the hardware or false to do only logical synchronization with the file system.
procThe pointer to the file processor object, whose Process method is called while the content of the file is synchronized. If it is nullptr, it is ignored.
Returns
The result status.

Implemented in tkrzw::TreeDBM, tkrzw::TinyDBM, tkrzw::StdTreeDBM, tkrzw::StdHashDBM, tkrzw::SkipDBM, tkrzw::ShardDBM, tkrzw::PolyDBM, tkrzw::HashDBM, tkrzw::CacheDBM, and tkrzw::BabyDBM.

◆ CopyFile()

virtual Status tkrzw::DBM::CopyFile ( const std::string &  dest_path)
virtual

Copies the content of the database file to another file.

Parameters
dest_pathA path to the destination file.
Returns
The result status.

Copying is done while the content is synchronized and stable. So, this method is suitable for making a backup file while running a database service.

Reimplemented in tkrzw::ShardDBM.

◆ Export()

virtual Status tkrzw::DBM::Export ( DBM dbm)
virtual

Exports all records to another database.

Parameters
dbmThe pointer to the destination database.
Returns
The result status.

◆ Inspect()

virtual std::vector<std::pair<std::string, std::string> > tkrzw::DBM::Inspect ( )
pure virtual

Inspects the database.

Returns
A vector of pairs of a property name and its value.

Implemented in tkrzw::TreeDBM, tkrzw::TinyDBM, tkrzw::StdTreeDBM, tkrzw::StdHashDBM, tkrzw::SkipDBM, tkrzw::ShardDBM, tkrzw::PolyDBM, tkrzw::HashDBM, tkrzw::CacheDBM, and tkrzw::BabyDBM.

◆ IsOpen()

virtual bool tkrzw::DBM::IsOpen ( ) const
pure virtual

Checks whether the database is open.

Returns
True if the database is open, or false if not.

Implemented in tkrzw::TreeDBM, tkrzw::TinyDBM, tkrzw::StdTreeDBM, tkrzw::StdHashDBM, tkrzw::SkipDBM, tkrzw::ShardDBM, tkrzw::PolyDBM, tkrzw::HashDBM, tkrzw::CacheDBM, and tkrzw::BabyDBM.

◆ IsWritable()

virtual bool tkrzw::DBM::IsWritable ( ) const
pure virtual

Checks whether the database is writable.

Returns
True if the database is writable, or false if not.

Implemented in tkrzw::TreeDBM, tkrzw::TinyDBM, tkrzw::StdTreeDBM, tkrzw::StdHashDBM, tkrzw::SkipDBM, tkrzw::ShardDBM, tkrzw::PolyDBM, tkrzw::HashDBM, tkrzw::CacheDBM, and tkrzw::BabyDBM.

◆ IsHealthy()

virtual bool tkrzw::DBM::IsHealthy ( ) const
pure virtual

Checks whether the database condition is healthy.

Returns
True if the database condition is healthy, or false if not.

Implemented in tkrzw::TreeDBM, tkrzw::TinyDBM, tkrzw::StdTreeDBM, tkrzw::StdHashDBM, tkrzw::SkipDBM, tkrzw::ShardDBM, tkrzw::PolyDBM, tkrzw::HashDBM, tkrzw::CacheDBM, and tkrzw::BabyDBM.

◆ IsOrdered()

virtual bool tkrzw::DBM::IsOrdered ( ) const
pure virtual

Checks whether ordered operations are supported.

Returns
True if ordered operations are supported, or false if not.

Implemented in tkrzw::TreeDBM, tkrzw::TinyDBM, tkrzw::StdTreeDBM, tkrzw::StdHashDBM, tkrzw::SkipDBM, tkrzw::ShardDBM, tkrzw::PolyDBM, tkrzw::HashDBM, tkrzw::CacheDBM, and tkrzw::BabyDBM.

◆ MakeIterator()

virtual std::unique_ptr<Iterator> tkrzw::DBM::MakeIterator ( )
pure virtual

Makes an iterator for each record.

Returns
The iterator for each record.

Implemented in tkrzw::TreeDBM, tkrzw::TinyDBM, tkrzw::StdTreeDBM, tkrzw::StdHashDBM, tkrzw::SkipDBM, tkrzw::ShardDBM, tkrzw::PolyDBM, tkrzw::HashDBM, tkrzw::CacheDBM, and tkrzw::BabyDBM.

◆ MakeDBM()

virtual std::unique_ptr<DBM> tkrzw::DBM::MakeDBM ( ) const
pure virtual

Make a new DBM object of the same concrete class.

Returns
The new file object.

Implemented in tkrzw::TreeDBM, tkrzw::TinyDBM, tkrzw::StdTreeDBM, tkrzw::StdHashDBM, tkrzw::SkipDBM, tkrzw::ShardDBM, tkrzw::PolyDBM, tkrzw::HashDBM, tkrzw::CacheDBM, and tkrzw::BabyDBM.