Tkrzw
Classes | Public Member Functions | Static Public Attributes | List of all members
tkrzw::CacheDBM Class Referencefinal

On-memory database manager implementation with LRU deletion. More...

#include <tkrzw_dbm_cache.h>

Classes

class  Iterator
 Iterator for each record. More...
 

Public Member Functions

 CacheDBM (int64_t cap_rec_num=-1, int64_t cap_mem_size=-1)
 Default constructor. More...
 
 CacheDBM (std::unique_ptr< File > file, int64_t cap_rec_num=-1, int64_t cap_mem_size=-1)
 Constructor with a file object. More...
 
virtual ~CacheDBM ()
 Destructor. More...
 
 CacheDBM (const CacheDBM &rhs)=delete
 Copy and assignment are disabled. More...
 
CacheDBMoperator= (const CacheDBM &rhs)=delete
 
Status Open (const std::string &path, bool writable, int32_t options=File::OPEN_DEFAULT) override
 Opens a database file. More...
 
Status Close () override
 Closes the database file. More...
 
Status Process (std::string_view key, RecordProcessor *proc, bool writable) override
 Processes a record with a processor. More...
 
Status ProcessEach (RecordProcessor *proc, bool writable) override
 Processes each and every record in the database with a processor. More...
 
Status Count (int64_t *count) override
 Gets the number of records. More...
 
Status GetFileSize (int64_t *size) override
 Gets the current file size of the database. More...
 
Status GetFilePath (std::string *path) override
 Gets the path of the database file. More...
 
Status Clear () override
 Removes all records. More...
 
Status Rebuild () override
 Rebuilds the entire database. More...
 
Status RebuildAdvanced (int64_t cap_rec_num=-1, int64_t cap_mem_size=-1)
 Rebuilds the entire database, in an advanced way. More...
 
Status ShouldBeRebuilt (bool *tobe) override
 Checks whether the database should be rebuilt. More...
 
Status Synchronize (bool hard, FileProcessor *proc=nullptr) override
 Synchronizes the content of the database to the file system. More...
 
std::vector< std::pair< std::string, std::string > > Inspect () override
 Inspects the database. More...
 
bool IsOpen () const override
 Checks whether the database is open. More...
 
bool IsWritable () const override
 Checks whether the database is writable. More...
 
bool IsHealthy () const override
 Checks whether the database condition is healthy. More...
 
bool IsOrdered () const override
 Checks whether ordered operations are supported. More...
 
std::unique_ptr< DBM::IteratorMakeIterator () override
 Makes an iterator for each record. More...
 
std::unique_ptr< DBMMakeDBM () const override
 Makes a new DBM object of the same concrete class. More...
 
int64_t GetEffectiveDataSize ()
 Gets the effective data size. More...
 
int64_t GetMemoryUsage ()
 Gets the current memory usage. More...
 
- Public Member Functions inherited from tkrzw::DBM
virtual ~DBM ()=default
 Destructor. 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 int64_t CountSimple ()
 Gets the number of records, in a simple way. More...
 
virtual int64_t GetFileSizeSimple ()
 Gets the current file size of the database, in a simple way. More...
 
virtual std::string GetFilePathSimple ()
 Gets the path of the database file, in a simple way. More...
 
virtual bool ShouldBeRebuiltSimple ()
 Checks whether the database should be rebuilt, in a simple way. 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...
 

Static Public Attributes

static constexpr int64_t DEFAULT_CAP_REC_NUM = 1048576
 The default value of the maximum number of records. More...
 

Detailed Description

On-memory database manager implementation with LRU deletion.

All operations are thread-safe; Multiple threads can access the same database concurrently.

Constructor & Destructor Documentation

◆ CacheDBM() [1/3]

tkrzw::CacheDBM::CacheDBM ( int64_t  cap_rec_num = -1,
int64_t  cap_mem_size = -1 
)

Default constructor.

Parameters
cap_rec_numThe maximum number of records. -1 means that the default value 1048576 is set.
cap_mem_sizeThe total memory size to use. -1 means unlimited. If the number of records or the total memory size exceeds the capacity LRU (least resente used) records are removed implicitly.

◆ CacheDBM() [2/3]

tkrzw::CacheDBM::CacheDBM ( std::unique_ptr< File file,
int64_t  cap_rec_num = -1,
int64_t  cap_mem_size = -1 
)

Constructor with a file object.

Parameters
fileThe file object to handle the data. The ownership is taken.
cap_rec_numThe maximum number of records. -1 means that the default value 1048576 is set. As the number of hash buckets is set by the maximum number of records, setting too large value is not good for space efficiency.
cap_mem_sizeThe total memory size to use. -1 means unlimited. If the number of records or the total memory size exceeds the capacity LRU (least resente used) records are removed implicitly.

◆ ~CacheDBM()

virtual tkrzw::CacheDBM::~CacheDBM ( )
virtual

Destructor.

◆ CacheDBM() [3/3]

tkrzw::CacheDBM::CacheDBM ( const CacheDBM rhs)
explicitdelete

Copy and assignment are disabled.

Member Function Documentation

◆ Open()

Status tkrzw::CacheDBM::Open ( const std::string &  path,
bool  writable,
int32_t  options = File::OPEN_DEFAULT 
)
overridevirtual

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. As this database is an on-memory database, you can set records and retrieve them without opening a file. If you open a file, records are loaded from the file.

Implements tkrzw::DBM.

◆ Close()

Status tkrzw::CacheDBM::Close ( )
overridevirtual

Closes the database file.

Returns
The result status. If a file is opened as writable, records are saved in the file.

Implements tkrzw::DBM.

◆ Process()

Status tkrzw::CacheDBM::Process ( std::string_view  key,
RecordProcessor proc,
bool  writable 
)
overridevirtual

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.

Implements tkrzw::DBM.

◆ ProcessEach()

Status tkrzw::CacheDBM::ProcessEach ( RecordProcessor proc,
bool  writable 
)
overridevirtual

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.

Implements tkrzw::DBM.

◆ Count()

Status tkrzw::CacheDBM::Count ( int64_t *  count)
overridevirtual

Gets the number of records.

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

Implements tkrzw::DBM.

◆ GetFileSize()

Status tkrzw::CacheDBM::GetFileSize ( int64_t *  size)
overridevirtual

Gets the current file size of the database.

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

Implements tkrzw::DBM.

◆ GetFilePath()

Status tkrzw::CacheDBM::GetFilePath ( std::string *  path)
overridevirtual

Gets the path of the database file.

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

Implements tkrzw::DBM.

◆ Clear()

Status tkrzw::CacheDBM::Clear ( )
overridevirtual

Removes all records.

Returns
The result status.

Implements tkrzw::DBM.

◆ Rebuild()

Status tkrzw::CacheDBM::Rebuild ( )
overridevirtual

Rebuilds the entire database.

Returns
The result status. The number of buckets is calculated implicitly.

Implements tkrzw::DBM.

◆ RebuildAdvanced()

Status tkrzw::CacheDBM::RebuildAdvanced ( int64_t  cap_rec_num = -1,
int64_t  cap_mem_size = -1 
)

Rebuilds the entire database, in an advanced way.

Parameters
cap_rec_numThe maximum number of records. -1 means that the current setting is kept.
cap_mem_sizeThe total memory size to use. -1 means that the current setting is kept.
Returns
The result status.

◆ ShouldBeRebuilt()

Status tkrzw::CacheDBM::ShouldBeRebuilt ( bool *  tobe)
overridevirtual

Checks whether the database should be rebuilt.

Parameters
tobeThe pointer to a boolean object to contain the result decision.
Returns
The result status. There's no need for the database to be rebuilt.

Implements tkrzw::DBM.

◆ Synchronize()

Status tkrzw::CacheDBM::Synchronize ( bool  hard,
FileProcessor proc = nullptr 
)
overridevirtual

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. If a file is opened as writable, records are saved in the file.

Implements tkrzw::DBM.

◆ Inspect()

std::vector<std::pair<std::string, std::string> > tkrzw::CacheDBM::Inspect ( )
overridevirtual

Inspects the database.

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

Implements tkrzw::DBM.

◆ IsOpen()

bool tkrzw::CacheDBM::IsOpen ( ) const
overridevirtual

Checks whether the database is open.

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

Implements tkrzw::DBM.

◆ IsWritable()

bool tkrzw::CacheDBM::IsWritable ( ) const
overridevirtual

Checks whether the database is writable.

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

Implements tkrzw::DBM.

◆ IsHealthy()

bool tkrzw::CacheDBM::IsHealthy ( ) const
overridevirtual

Checks whether the database condition is healthy.

Returns
Always true. On-memory databases never cause system errors.

Implements tkrzw::DBM.

◆ IsOrdered()

bool tkrzw::CacheDBM::IsOrdered ( ) const
overridevirtual

Checks whether ordered operations are supported.

Returns
Always false. Ordered operations are not supported.

Implements tkrzw::DBM.

◆ MakeIterator()

std::unique_ptr<DBM::Iterator> tkrzw::CacheDBM::MakeIterator ( )
overridevirtual

Makes an iterator for each record.

Returns
The iterator for each record.

Implements tkrzw::DBM.

◆ MakeDBM()

std::unique_ptr<DBM> tkrzw::CacheDBM::MakeDBM ( ) const
overridevirtual

Makes a new DBM object of the same concrete class.

Returns
The new file object.

Implements tkrzw::DBM.

◆ GetEffectiveDataSize()

int64_t tkrzw::CacheDBM::GetEffectiveDataSize ( )

Gets the effective data size.

Returns
The effective data size, or -1 on failure. The effective data size means the total size of the keys and the values.

◆ GetMemoryUsage()

int64_t tkrzw::CacheDBM::GetMemoryUsage ( )

Gets the current memory usage.

Returns
The current memory usage, or -1 on failure. The memory usage is estimated by the effective data size and the nuber of records.

Member Data Documentation

◆ DEFAULT_CAP_REC_NUM

constexpr int64_t tkrzw::CacheDBM::DEFAULT_CAP_REC_NUM = 1048576
staticconstexpr

The default value of the maximum number of records.