File database manager implementation based on hash table. More...

#include <tkrzw_dbm_hash.h>

Classes
class	Iterator
	Iterator for each record. More...

struct	TuningParameters
	Tuning parameters for the database. More...

Public Types
enum	UpdateMode : int32_t { UPDATE_DEFAULT = 0 , UPDATE_IN_PLACE = 1 , UPDATE_APPENDING = 2 }
	Enumeration for update modes. More...

enum	RecordCRCMode : int32_t { RECORD_CRC_DEFAULT = 0 , RECORD_CRC_NONE = 1 , RECORD_CRC_8 = 2 , RECORD_CRC_16 = 3 , RECORD_CRC_32 = 4 }
	Enumeration for record CRC modes. More...

enum	RecordCompressionMode : int32_t { RECORD_COMP_DEFAULT = 0 , RECORD_COMP_NONE = 1 , RECORD_COMP_ZLIB = 2 , RECORD_COMP_ZSTD = 3 , RECORD_COMP_LZ4 = 4 , RECORD_COMP_LZMA = 5 , RECORD_COMP_RC4 = 6 , RECORD_COMP_AES = 7 }
	Enumeration for record compression modes. More...

enum	RestoreMode : int32_t { RESTORE_DEFAULT = 0 , RESTORE_SYNC = 1 , RESTORE_READ_ONLY = 2 , RESTORE_NOOP = 3 , RESTORE_NO_SHORTCUTS = 1 << 16 , RESTORE_WITH_HARDSYNC = 1 << 17 }
	Enumeration for restore modes. More...

Public Types inherited from tkrzw::DBM
typedef std::function< std::string_view(std::string_view, std::string_view)>	RecordLambdaType
	Lambda function type to process a record. More...

Public Member Functions
	HashDBM ()
	Default constructor. More...

	HashDBM (std::unique_ptr< File > file)
	Constructor with a file object. More...

	~HashDBM ()
	Destructor. More...

	HashDBM (const HashDBM &rhs)=delete
	Copy and assignment are disabled. More...

HashDBM &	operator= (const HashDBM &rhs)=delete

Status	Open (const std::string &path, bool writable, int32_t options=File::OPEN_DEFAULT) override
	Opens a database file. More...

Status	OpenAdvanced (const std::string &path, bool writable, int32_t options=File::OPEN_DEFAULT, const TuningParameters &tuning_params=TuningParameters())
	Opens a database file, in an advanced way. 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	Get (std::string_view key, std::string *value=nullptr) override
	Gets the value of a record of a key. More...

Status	Set (std::string_view key, std::string_view value, bool overwrite=true, std::string *old_value=nullptr) override
	Sets a record of a key and a value. More...

Status	Remove (std::string_view key, std::string *old_value=nullptr) override
	Removes a record of a key. More...

Status	ProcessMulti (const std::vector< std::pair< std::string_view, DBM::RecordProcessor * >> &key_proc_pairs, bool writable) override
	Processes multiple records with processors. More...

Status	ProcessFirst (RecordProcessor *proc, bool writable) override
	Processes the first 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	GetTimestamp (double *timestamp) override
	Gets the timestamp in seconds of the last modified time. More...

Status	Clear () override
	Removes all records. More...

Status	Rebuild () override
	Rebuilds the entire database. More...

Status	RebuildAdvanced (const TuningParameters &tuning_params=TuningParameters(), bool skip_broken_records=false, bool sync_hard=false)
	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	IsAutoRestored () const
	Checks whether the database has been restored automatically. More...

bool	IsOrdered () const override
	Checks whether ordered operations are supported. More...

std::unique_ptr< DBM::Iterator >	MakeIterator () override
	Makes an iterator for each record. More...

std::unique_ptr< DBM >	MakeDBM () const override
	Makes a new DBM object of the same concrete class. More...

UpdateLogger *	GetUpdateLogger () const override
	Gets the logger to write all update operations. More...

void	SetUpdateLogger (UpdateLogger *update_logger) override
	Sets the logger to write all update operations. More...

File *	GetInternalFile () const
	Gets the pointer to the internal file object. More...

int64_t	GetEffectiveDataSize ()
	Gets the effective data size. More...

int32_t	GetDatabaseType ()
	Gets the database type. More...

Status	SetDatabaseType (uint32_t db_type)
	Sets the database type. More...

std::string	GetOpaqueMetadata ()
	Gets the opaque metadata. More...

Status	SetOpaqueMetadata (const std::string &opaque)
	Sets the opaque metadata. More...

int64_t	CountBuckets ()
	Gets the number of buckets of the hash table. More...

int64_t	CountUsedBuckets ()
	Gets the number of used buckets of the hash table. More...

UpdateMode	GetUpdateMode ()
	Gets the current update mode. More...

Status	SetUpdateModeAppending ()
	Set the update mode appending. More...

Status	ImportFromFileForward (File *file, bool skip_broken_records, int64_t record_base, int64_t end_offset)
	Imports records from another hash database file, in a forward manner. More...

Status	ImportFromFileForward (const std::string &path, bool skip_broken_records, int64_t record_base, int64_t end_offset)
	Imports records from another hash database file, in a forward manner. More...

Status	ImportFromFileBackward (File *file, bool skip_broken_records, int64_t record_base, int64_t end_offset)
	Imports records from another hash database file, in a backward manner. More...

Status	ImportFromFileBackward (const std::string &path, bool skip_broken_records, int64_t record_base, int64_t end_offset)
	Imports records from another hash database file, in a backward manner. More...

Status	ValidateHashBuckets ()
	Validate all buckets in the hash table. More...

Status	ValidateRecords (int64_t record_base, int64_t end_offset)
	Validates records in a region. More...

Public Member Functions inherited from tkrzw::DBM
virtual	~DBM ()=default
	Destructor. More...

virtual Status	Process (std::string_view key, RecordLambdaType rec_lambda, bool writable)
	Processes a record with a lambda function. 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 Status	GetMulti (const std::vector< std::string_view > &keys, std::map< std::string, std::string > *records)
	Gets the values of multiple records of keys, with a string view vector. More...

virtual Status	GetMulti (const std::initializer_list< std::string_view > &keys, std::map< std::string, std::string > *records)
	Gets the values of multiple records of keys, with an initializer list. More...

virtual Status	GetMulti (const std::vector< std::string > &keys, std::map< std::string, std::string > *records)
	Gets the values of multiple records of keys, with a string vector. More...

virtual Status	SetMulti (const std::map< std::string_view, std::string_view > &records, bool overwrite=true)
	Sets multiple records, with a map of string views. More...

virtual Status	SetMulti (const std::initializer_list< std::pair< std::string_view, std::string_view >> &records, bool overwrite=true)
	Sets multiple records, with an initializer list. 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	RemoveMulti (const std::vector< std::string_view > &keys)
	Removes records of keys, with a string view vector. More...

virtual Status	RemoveMulti (const std::initializer_list< std::string_view > &keys)
	Removes records of keys, with an initializer list. More...

virtual Status	RemoveMulti (const std::vector< std::string > &keys)
	Removes records of keys, with a string vector. 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	AppendMulti (const std::map< std::string_view, std::string_view > &records, std::string_view delim="")
	Appends data to multiple records, with a map of string views. More...

virtual Status	AppendMulti (const std::initializer_list< std::pair< std::string_view, std::string_view >> &records, std::string_view delim="")
	Appends data to multiple records, with an initializer list. More...

virtual Status	AppendMulti (const std::map< std::string, std::string > &records, std::string_view delim="")
	Appends data to multiple records, with a map of strings. More...

virtual Status	CompareExchange (std::string_view key, std::string_view expected, std::string_view desired, std::string actual=nullptr, bool found=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...

virtual 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	ProcessMulti (const std::vector< std::pair< std::string_view, RecordProcessor * >> &key_proc_pairs, bool writable)=0
	Processes multiple records with processors. More...

virtual Status	ProcessMulti (const std::vector< std::pair< std::string_view, RecordLambdaType >> &key_lambda_pairs, bool writable)
	Processes multiple records with lambda functions. More...

virtual Status	CompareExchangeMulti (const std::vector< std::pair< std::string_view, std::string_view >> &expected, const std::vector< std::pair< std::string_view, std::string_view >> &desired)
	Compares the values of records and exchanges if the condition meets. More...

virtual Status	Rekey (std::string_view old_key, std::string_view new_key, bool overwrite=true, bool copying=false, std::string *value=nullptr)
	Changes the key of a record. More...

virtual Status	ProcessFirst (RecordLambdaType rec_lambda, bool writable)
	Processes the first record with a lambda function. More...

virtual Status	PopFirst (std::string key=nullptr, std::string value=nullptr)
	Gets the first record and removes it. More...

virtual Status	PushLast (std::string_view value, double wtime=-1, std::string *key=nullptr)
	Adds a record with a key of the current timestamp. More...

virtual Status	ProcessEach (RecordLambdaType rec_lambda, bool writable)
	Processes each and every record in the database with a lambda function. 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 double	GetTimestampSimple ()
	Gets the timestamp of the last modified time, in a simple way. More...

virtual bool	ShouldBeRebuiltSimple ()
	Checks whether the database should be rebuilt, in a simple way. More...

virtual Status	CopyFileData (const std::string &dest_path, bool sync_hard=false)
	Copies the content of the database file to another file. More...

virtual Status	Export (DBM *dest_dbm)
	Exports all records to another database. More...

const std::type_info &	GetType () const
	Gets the type information of the actual class. More...

Static Public Member Functions
static Status	ReadMetadata (File file, int32_t cyclic_magic, int32_t pkg_major_version, int32_t pkg_minor_version, int32_t static_flags, int32_t offset_width, int32_t align_pow, int32_t closure_flags, int64_t num_buckets, int64_t num_records, int64_t eff_data_size, int64_t file_size, int64_t mod_time, int32_t db_type, std::string *opaque)
	Reads metadata from a database file. More...

static Status	FindRecordBase (File file, int64_t record_base, int32_t static_flags, int32_t offset_width, int32_t align_pow, int64_t last_sync_size)
	Finds the record base of a hash database file. More...

static int32_t	GetCRCWidthFromStaticFlags (int32_t static_flags)
	Gets the record CRC width from the static flags. More...

static std::unique_ptr< Compressor >	MakeCompressorFromStaticFlags (int32_t static_flags, std::string_view cipher_key="")
	Makes the compressor from the static flags. More...

static bool	CheckRecordCompressionModeIsSupported (RecordCompressionMode mode)
	Checks whether a record compression mode is supported on the platform. More...

static Status	RestoreDatabase (const std::string &old_file_path, const std::string &new_file_path, int64_t end_offset, std::string_view cipher_key="")
	Restores a broken database as a new healthy database. More...

Static Public Attributes
static constexpr int32_t	DEFAULT_OFFSET_WIDTH = 4
	The default value of the offset width. More...

static constexpr int32_t	DEFAULT_ALIGN_POW = 3
	The default value of the alignment power. More...

static constexpr int64_t	DEFAULT_NUM_BUCKETS = 1048583
	The default value of the number of buckets. More...

static constexpr int32_t	DEFAULT_FBP_CAPACITY = 2048
	The default value of the capacity of the free block pool. More...

static constexpr int32_t	DEFAULT_MIN_READ_SIZE = 48
	The default value of the minimum reading size to read a record. More...

static constexpr int32_t	OPAQUE_METADATA_SIZE = 64
	The size of the opaque metadata. More...

Static Public Attributes inherited from tkrzw::DBM
static const std::string_view	ANY_DATA
	The special string_view value to represent any data. More...

Detailed Description

File database manager implementation based on hash table.

All operations are thread-safe; Multiple threads can access the same database concurrently. Every opened database must be closed explicitly to avoid data corruption.

Member Enumeration Documentation

◆ UpdateMode

enum tkrzw::HashDBM::UpdateMode : int32_t

Enumeration for update modes.

Enumerator
UPDATE_DEFAULT	The default behavior: in-place or to succeed the current mode.
UPDATE_IN_PLACE	To do in-place writing.
UPDATE_APPENDING	To do appending writing.

◆ RecordCRCMode

enum tkrzw::HashDBM::RecordCRCMode : int32_t

Enumeration for record CRC modes.

Enumerator
RECORD_CRC_DEFAULT	The default behavior: no CRC or to succeed the current mode.
RECORD_CRC_NONE	To add no CRC to each record.
RECORD_CRC_8	To add CRC-8 to each record.
RECORD_CRC_16	To add CRC-16 to each record.
RECORD_CRC_32	To add CRC-32 to each record.

◆ RecordCompressionMode

enum tkrzw::HashDBM::RecordCompressionMode : int32_t

Enumeration for record compression modes.

Enumerator
RECORD_COMP_DEFAULT	The default behavior: no compression or to succeed the current mode.
RECORD_COMP_NONE	To do no compression.
RECORD_COMP_ZLIB	To compress with ZLib.
RECORD_COMP_ZSTD	To compress with ZStd.
RECORD_COMP_LZ4	To compress with LZ4.
RECORD_COMP_LZMA	To compress with LZMA.
RECORD_COMP_RC4	To cipher with RC4.
RECORD_COMP_AES	To cipher with AES.

◆ RestoreMode

enum tkrzw::HashDBM::RestoreMode : int32_t

Enumeration for restore modes.

Enumerator
RESTORE_DEFAULT	The default behavior: to restore as many records as possible.
RESTORE_SYNC	To restore to the last synchronized state.
RESTORE_READ_ONLY	To make the database read-only.
RESTORE_NOOP	To do nothing.
RESTORE_NO_SHORTCUTS	Additional bit to not apply shortcuts.
RESTORE_WITH_HARDSYNC	Additional bit to do physical synchronization.

Constructor & Destructor Documentation

◆ HashDBM() [1/3]

tkrzw::HashDBM::HashDBM ( )

Default constructor.

MemoryMapParallelFile is used to handle the data.

◆ HashDBM() [2/3]

tkrzw::HashDBM::HashDBM ( std::unique_ptr< File > file )

explicit

Constructor with a file object.

Parameters

file	The file object to handle the data. The ownership is taken.

◆ ~HashDBM()

tkrzw::HashDBM::~HashDBM ( )

Destructor.

◆ HashDBM() [3/3]

tkrzw::HashDBM::HashDBM ( const HashDBM & rhs )

explicitdelete

Copy and assignment are disabled.

Member Function Documentation

◆ Open()

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

overridevirtual

Opens a database file.

Parameters

path	A path of the file.
writable	If true, the file is writable. If false, it is read-only.
options	Bit-sum options of File::OpenOption enums for opening the file.

Returns: The result status.

Precondition: The database is not opened.

Implements tkrzw::DBM.

◆ OpenAdvanced()

Status tkrzw::HashDBM::OpenAdvanced	(	const std::string &	path,
		bool	writable,
		int32_t	options = `File::OPEN_DEFAULT`,
		const TuningParameters &	tuning_params = `TuningParameters()`
	)

Opens a database file, in an advanced way.

Parameters

path	A path of the file.
writable	If true, the file is writable. If false, it is read-only.
options	Bit-sum options for opening the file.
tuning_params	A structure for tuning parameters.

Returns: The result status.

Precondition: The database is not opened.

◆ Close()

Status tkrzw::HashDBM::Close ( )

overridevirtual

Closes the database file.

Returns: The result status.

Precondition: The database is opened.

Implements tkrzw::DBM.

◆ Process()

Status tkrzw::HashDBM::Process	(	std::string_view	key,
		RecordProcessor *	proc,
		bool	writable
	)

overridevirtual

Processes a record with a processor.

Parameters

key	The key of the record.
proc	The pointer to the processor object.
writable	True if the processor can edit the record.

Returns: The result status.

Precondition: The database is opened. The writable parameter should be consistent to the open mode.

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

Implements tkrzw::DBM.

◆ Get()

Status tkrzw::HashDBM::Get	(	std::string_view	key,
		std::string *	value = `nullptr`
	)

overridevirtual

Gets the value of a record of a key.

Parameters

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

Returns: The result status. If there's no matching record, NOT_FOUND_ERROR is returned.

Precondition: The database is opened.

Reimplemented from tkrzw::DBM.

◆ Set()

Status tkrzw::HashDBM::Set	(	std::string_view	key,
		std::string_view	value,
		bool	overwrite = `true`,
		std::string *	old_value = `nullptr`
	)

overridevirtual

Sets a record of a key and a value.

Parameters

key	The key of the record.
value	The value of the record.
overwrite	Whether 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.
old_value	The pointer to a string object to contain the old value. Assignment is done even on the duplication error. If it is nullptr, it is ignored.

Returns: The result status. If overwriting is abandoned, DUPLICATION_ERROR is returned.

Precondition: The database is opened as writable.

Reimplemented from tkrzw::DBM.

◆ Remove()

Status tkrzw::HashDBM::Remove	(	std::string_view	key,
		std::string *	old_value = `nullptr`
	)

overridevirtual

Removes a record of a key.

Parameters

key	The key of the record.
old_value	The pointer to a string object to contain the old value. If it is nullptr, it is ignored.

Returns: The result status. If there's no matching record, NOT_FOUND_ERROR is returned.

Precondition: The database is opened as writable.

Reimplemented from tkrzw::DBM.

◆ ProcessMulti()

Status tkrzw::HashDBM::ProcessMulti	(	const std::vector< std::pair< std::string_view, DBM::RecordProcessor * >> &	key_proc_pairs,
		bool	writable
	)

override

Processes multiple records with processors.

Parameters

key_proc_pairs	Pairs of the keys and their processor objects.
writable	True if the processors can edit the records.

Returns: The result status.

Precondition: The database is opened. The writable parameter should be consistent to the open mode.

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

◆ ProcessFirst()

Status tkrzw::HashDBM::ProcessFirst	(	RecordProcessor *	proc,
		bool	writable
	)

overridevirtual

Processes the first record with a processor.

Parameters

proc	The pointer to the processor object.
writable	True if the processor can edit the record.

Returns: The result status.

Precondition: The database is opened. The writable parameter should be consistent to the open mode.

If the first record exists, the ProcessFull of the processor is called. Otherwise, this method fails and no method of the processor is called. This method can be slow because it can scan all buckets.

Implements tkrzw::DBM.

◆ ProcessEach()

Status tkrzw::HashDBM::ProcessEach	(	RecordProcessor *	proc,
		bool	writable
	)

overridevirtual

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

Parameters

proc	The pointer to the processor object.
writable	True if the processor can edit the record.

Returns: The result status.

Precondition: The database is opened. The writable parameter should be consistent to the open mode.

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::HashDBM::Count ( int64_t * count )

overridevirtual

Gets the number of records.

Parameters

count The pointer to an integer object to contain the result count.

Returns: The result status.

Precondition: The database is opened.

Implements tkrzw::DBM.

◆ GetFileSize()

Status tkrzw::HashDBM::GetFileSize ( int64_t * size )

overridevirtual

Gets the current file size of the database.

Parameters

size	The pointer to an integer object to contain the result size.

Returns: The result status.

Precondition: The database is opened.

Implements tkrzw::DBM.

◆ GetFilePath()

Status tkrzw::HashDBM::GetFilePath ( std::string * path )

overridevirtual

Gets the path of the database file.

Parameters

path	The pointer to a string object to contain the result path.

Returns: The result status.

Precondition: The database is opened.

Implements tkrzw::DBM.

◆ GetTimestamp()

Status tkrzw::HashDBM::GetTimestamp ( double * timestamp )

overridevirtual

Gets the timestamp in seconds of the last modified time.

Parameters

timestamp The pointer to a double object to contain the timestamp.

Returns: The result status.

Precondition: The database is opened.

The timestamp is updated when the database opened in the writable mode is closed or synchronized, even if no updating opertion is done.

Implements tkrzw::DBM.

◆ Clear()

Status tkrzw::HashDBM::Clear ( )

overridevirtual

Removes all records.

Returns: The result status.

Precondition: The database is opened as writable.

Implements tkrzw::DBM.

◆ Rebuild()

Status tkrzw::HashDBM::Rebuild ( )

overridevirtual

Rebuilds the entire database.

Returns: The result status.

Precondition: The database is opened as writable.

Rebuilding a database is useful to reduce the size of the file by solving fragmentation. All tuning parameters are succeeded or calculated implicitly.

Implements tkrzw::DBM.

◆ RebuildAdvanced()

Status tkrzw::HashDBM::RebuildAdvanced	(	const TuningParameters &	tuning_params = `TuningParameters()`,
		bool	skip_broken_records = `false`,
		bool	sync_hard = `false`
	)

Rebuilds the entire database, in an advanced way.

Parameters

tuning_params	A structure for tuning parameters. The default value of each parameter means that the current setting is succeeded or calculated implicitly.
skip_broken_records	If true, the operation continues even if there are broken records which can be skipped.
sync_hard	True to do physical synchronization with the hardware before finishing the rebuilt file.

Returns: The result status.

Precondition: The database is opened as writable.

Rebuilding a database is useful to reduce the size of the file by solving fragmentation.

◆ ShouldBeRebuilt()

Status tkrzw::HashDBM::ShouldBeRebuilt ( bool * tobe )

overridevirtual

Checks whether the database should be rebuilt.

Parameters

tobe	The pointer to a boolean object to contain the result decision.

Returns: The result status.

Precondition: The database is opened.

Implements tkrzw::DBM.

◆ Synchronize()

Status tkrzw::HashDBM::Synchronize	(	bool	hard,
		FileProcessor *	proc = `nullptr`
	)

overridevirtual

Synchronizes the content of the database to the file system.

Parameters

hard	True to do physical synchronization with the hardware or false to do only logical synchronization with the file system.
proc	The 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.

Precondition: The database is opened as writable.

Implements tkrzw::DBM.

◆ Inspect()

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

overridevirtual

Inspects the database.

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

Implements tkrzw::DBM.

◆ IsOpen()

bool tkrzw::HashDBM::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::HashDBM::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::HashDBM::IsHealthy ( ) const

overridevirtual

Checks whether the database condition is healthy.

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

Precondition: The database is opened.

Implements tkrzw::DBM.

◆ IsAutoRestored()

bool tkrzw::HashDBM::IsAutoRestored ( ) const

Checks whether the database has been restored automatically.

Returns: True if the database condition has been restored by the last Open method.

Precondition: The database is opened.

◆ IsOrdered()

bool tkrzw::HashDBM::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::HashDBM::MakeIterator ( )

overridevirtual

Makes an iterator for each record.

Returns: The iterator for each record.

Precondition: The database is opened.

Implements tkrzw::DBM.

◆ MakeDBM()

std::unique_ptr<DBM> tkrzw::HashDBM::MakeDBM ( ) const

overridevirtual

Makes a new DBM object of the same concrete class.

Returns: The new DBM object.

Implements tkrzw::DBM.

◆ GetUpdateLogger()

UpdateLogger* tkrzw::HashDBM::GetUpdateLogger ( ) const

overridevirtual

Gets the logger to write all update operations.

Returns: The update logger if it has been set or nullptr if it hasn't.

Implements tkrzw::DBM.

◆ SetUpdateLogger()

void tkrzw::HashDBM::SetUpdateLogger ( UpdateLogger * update_logger )

overridevirtual

Sets the logger to write all update operations.

Parameters

update_logger The pointer to the update logger object. Ownership is not taken. If it is nullptr, no logger is used.

Implements tkrzw::DBM.

◆ GetInternalFile()

File* tkrzw::HashDBM::GetInternalFile ( ) const

Gets the pointer to the internal file object.

Returns: The pointer to the internal file object.

Accessing the internal file viorates encapsulation policy. This should be used only for testing and debugging.

◆ GetEffectiveDataSize()

int64_t tkrzw::HashDBM::GetEffectiveDataSize ( )

Gets the effective data size.

Returns: The effective data size, or -1 on failure.

Precondition: The database is opened.

The effective data size means the total size of the keys and the values. This figure might deviate if auto restore happens.

◆ GetDatabaseType()

int32_t tkrzw::HashDBM::GetDatabaseType ( )

Gets the database type.

Returns: The database type, or -1 on failure.

Precondition: The database is opened.

◆ SetDatabaseType()

Status tkrzw::HashDBM::SetDatabaseType ( uint32_t db_type )

Sets the database type.

Parameters

db_type The database type.

Returns: The result status.

Precondition: The database is opened as writable.

This data is just for applications and not used by the database implementation.

◆ GetOpaqueMetadata()

std::string tkrzw::HashDBM::GetOpaqueMetadata ( )

Gets the opaque metadata.

Returns: The opaque metadata, or an empty string on failure.

Precondition: The database is opened.

◆ SetOpaqueMetadata()

Status tkrzw::HashDBM::SetOpaqueMetadata ( const std::string & opaque )

Sets the opaque metadata.

Parameters

opaque The opaque metadata, of which leading 64 bytes are stored in the file.

Returns: The result status.

Precondition: The database is opened as writable.

This data is just for applications and not used by the database implementation.

◆ CountBuckets()

int64_t tkrzw::HashDBM::CountBuckets ( )

Gets the number of buckets of the hash table.

Returns: The number of buckets of the hash table, or -1 on failure.

Precondition: The database is opened.

◆ CountUsedBuckets()

int64_t tkrzw::HashDBM::CountUsedBuckets ( )

Gets the number of used buckets of the hash table.

Returns: The number of used buckets of the hash table, or -1 on failure.

Precondition: The database is opened.

◆ GetUpdateMode()

UpdateMode tkrzw::HashDBM::GetUpdateMode ( )

Gets the current update mode.

Returns: The current update mode or UPDATE_DEFAULT on failure.

◆ SetUpdateModeAppending()

Status tkrzw::HashDBM::SetUpdateModeAppending ( )

Set the update mode appending.

Precondition: The database is opened as writable.

Whereas it is allowed to change a database in the in-place mode to the appending mode, the opposite direction is not allowed.

◆ ImportFromFileForward() [1/2]

Status tkrzw::HashDBM::ImportFromFileForward	(	File *	file,
		bool	skip_broken_records,
		int64_t	record_base,
		int64_t	end_offset
	)

Imports records from another hash database file, in a forward manner.

Parameters

file	A file object of the other hash database file.
skip_broken_records	If true, the operation continues even if there are broken records which can be skipped.
record_base	The beginning offset of records to read. Negative means the beginning of the record section.
end_offset	The exclusive end offset of records to read. Negative means unlimited. 0 means the size when the database is synched or closed properly.

Returns: The result status.

Precondition: The database is opened.

◆ ImportFromFileForward() [2/2]

Status tkrzw::HashDBM::ImportFromFileForward	(	const std::string &	path,
		bool	skip_broken_records,
		int64_t	record_base,
		int64_t	end_offset
	)

Imports records from another hash database file, in a forward manner.

Parameters

path	A path of the other hash database file.
skip_broken_records	If true, the operation continues even if there are broken records which can be skipped.
record_base	The beginning offset of records to read. Negative means the beginning of the record section.
end_offset	The exclusive end offset of records to read. Negative means unlimited. 0 means the size when the database is synched or closed properly.

Returns: The result status.

Precondition: The database is opened.

◆ ImportFromFileBackward() [1/2]

Status tkrzw::HashDBM::ImportFromFileBackward	(	File *	file,
		bool	skip_broken_records,
		int64_t	record_base,
		int64_t	end_offset
	)

Imports records from another hash database file, in a backward manner.

Parameters

file	A file object of the other hash database file.
skip_broken_records	If true, the operation continues even if there are broken records which can be skipped.
record_base	The beginning offset of records to read. Negative means the beginning of the record section.
end_offset	The exclusive end offset of records to read. Negative means unlimited. 0 means the size when the database is synched or closed properly.

Returns: The result status.

Precondition: The database is opened.

◆ ImportFromFileBackward() [2/2]

Status tkrzw::HashDBM::ImportFromFileBackward	(	const std::string &	path,
		bool	skip_broken_records,
		int64_t	record_base,
		int64_t	end_offset
	)

Imports records from another hash database file, in a backward manner.

Parameters

path	A path of the other hash database file.
skip_broken_records	If true, the operation continues even if there are broken records which can be skipped.
record_base	The beginning offset of records to read. Negative means the beginning of the record section.
end_offset	The exclusive end offset of records to read. Negative means unlimited. 0 means the size when the database is synched or closed properly.

Returns: The result status.

Precondition: The database is opened.

◆ ValidateHashBuckets()

Status tkrzw::HashDBM::ValidateHashBuckets ( )

Validate all buckets in the hash table.

Returns: The result status.

◆ ValidateRecords()

Status tkrzw::HashDBM::ValidateRecords	(	int64_t	record_base,
		int64_t	end_offset
	)

Validates records in a region.

Parameters

record_base	The beginning offset of records to check. Negative means the beginning of the record section. 0 means the size when the database is synched or closed properly.
end_offset	The exclusive end offset of records to check. Negative means unlimited. 0 means the size when the database is synched or closed properly.

Returns: The result status.

◆ ReadMetadata()

static Status tkrzw::HashDBM::ReadMetadata	(	File *	file,
		int32_t *	cyclic_magic,
		int32_t *	pkg_major_version,
		int32_t *	pkg_minor_version,
		int32_t *	static_flags,
		int32_t *	offset_width,
		int32_t *	align_pow,
		int32_t *	closure_flags,
		int64_t *	num_buckets,
		int64_t *	num_records,
		int64_t *	eff_data_size,
		int64_t *	file_size,
		int64_t *	mod_time,
		int32_t *	db_type,
		std::string *	opaque
	)

static

Reads metadata from a database file.

Parameters

file	A file object having opened the database file.
cyclic_magic	The pointer to a variable to store the cyclic magic data.
pkg_major_version	The pointer to a variable to store the package major version.
pkg_minor_version	The pointer to a variable to store the package minor version.
static_flags	The pointer to a variable to store the static flags.
offset_width	The pointer to a variable to store the offset width.
align_pow	The pointer to a variable to store the alignment power.
closure_flags	The pointer to a variable to store the closure flags.
num_buckets	The pointer to a variable to store the number of buckets.
num_records	The pointer to a variable to store the number of records.
eff_data_size	The pointer to a variable to store the effective data size.
file_size	The pointer to a variable to store the file size.
mod_time	The pointer to a variable to store the last modified time.
db_type	The pointer to a variable to store the database type.
opaque	The pointer to a variable to store the opaque data.

Returns: The result status.

If the leading magic data is inconsistent, it returns failure. If the cyclic magic data is inconsistent, it returns success and -1 is assigned to cyclic_magic.

◆ FindRecordBase()

static Status tkrzw::HashDBM::FindRecordBase	(	File *	file,
		int64_t *	record_base,
		int32_t *	static_flags,
		int32_t *	offset_width,
		int32_t *	align_pow,
		int64_t *	last_sync_size
	)

static

Finds the record base of a hash database file.

Parameters

file	A file object having opened the database file.
record_base	The pointer to an integer to store the record base offset.
static_flags	The pointer to an integer to store the static flags.
offset_width	The pointer to an integer to store the offset width.
align_pow	The pointer to an integer to store the alignment power.
last_sync_size	The pointer to an integer to store the file size when the database was synched or closed properly at the last time. This size is zero, if the metadata is broken.

Returns: The result status.

◆ GetCRCWidthFromStaticFlags()

static int32_t tkrzw::HashDBM::GetCRCWidthFromStaticFlags ( int32_t static_flags )

static

Gets the record CRC width from the static flags.

Parameters

static_flags The static flags.

Returns: The record CRC width.

◆ MakeCompressorFromStaticFlags()

static std::unique_ptr<Compressor> tkrzw::HashDBM::MakeCompressorFromStaticFlags	(	int32_t	static_flags,
		std::string_view	cipher_key = `""`
	)

static

Makes the compressor from the static flags.

Parameters

static_flags	The static flags.
cipher_key	The encryption key for cipher compressors.

Returns: The compressor object or nullptr for no compression.

◆ CheckRecordCompressionModeIsSupported()

static bool tkrzw::HashDBM::CheckRecordCompressionModeIsSupported ( RecordCompressionMode mode )

static

Checks whether a record compression mode is supported on the platform.

Parameters

mode	The record compression mode.

Returns: True if the record compression mode is supported on the platform.

◆ RestoreDatabase()

static Status tkrzw::HashDBM::RestoreDatabase	(	const std::string &	old_file_path,
		const std::string &	new_file_path,
		int64_t	end_offset,
		std::string_view	cipher_key = `""`
	)

static

Restores a broken database as a new healthy database.

Parameters

old_file_path	The path of the broken database.
new_file_path	The path of the new database to be created.
end_offset	The exclusive end offset of records to read. Negative means unlimited. 0 means the size when the database is synched or closed properly.
cipher_key	The encryption key for cipher compressors.

Returns: The result status.

Member Data Documentation

◆ DEFAULT_OFFSET_WIDTH

constexpr int32_t tkrzw::HashDBM::DEFAULT_OFFSET_WIDTH = 4

staticconstexpr

The default value of the offset width.

◆ DEFAULT_ALIGN_POW

constexpr int32_t tkrzw::HashDBM::DEFAULT_ALIGN_POW = 3

staticconstexpr

The default value of the alignment power.

◆ DEFAULT_NUM_BUCKETS

constexpr int64_t tkrzw::HashDBM::DEFAULT_NUM_BUCKETS = 1048583

staticconstexpr

The default value of the number of buckets.

◆ DEFAULT_FBP_CAPACITY

constexpr int32_t tkrzw::HashDBM::DEFAULT_FBP_CAPACITY = 2048

staticconstexpr

The default value of the capacity of the free block pool.

◆ DEFAULT_MIN_READ_SIZE

constexpr int32_t tkrzw::HashDBM::DEFAULT_MIN_READ_SIZE = 48

staticconstexpr

The default value of the minimum reading size to read a record.

◆ OPAQUE_METADATA_SIZE

constexpr int32_t tkrzw::HashDBM::OPAQUE_METADATA_SIZE = 64

staticconstexpr

The size of the opaque metadata.

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ UpdateMode

◆ RecordCRCMode

◆ RecordCompressionMode

◆ RestoreMode

Constructor & Destructor Documentation

◆ HashDBM() [1/3]

◆ HashDBM() [2/3]

◆ ~HashDBM()

◆ HashDBM() [3/3]

Member Function Documentation

◆ Open()

◆ OpenAdvanced()

◆ Close()

◆ Process()

◆ Get()

◆ Set()

◆ Remove()

◆ ProcessMulti()

◆ ProcessFirst()

◆ ProcessEach()

◆ Count()

◆ GetFileSize()

◆ GetFilePath()

◆ GetTimestamp()

◆ Clear()

◆ Rebuild()

◆ RebuildAdvanced()

◆ ShouldBeRebuilt()

◆ Synchronize()

◆ Inspect()

◆ IsOpen()

◆ IsWritable()

◆ IsHealthy()

◆ IsAutoRestored()

◆ IsOrdered()

◆ MakeIterator()

◆ MakeDBM()

◆ GetUpdateLogger()

◆ SetUpdateLogger()

◆ GetInternalFile()

◆ GetEffectiveDataSize()

◆ GetDatabaseType()

◆ SetDatabaseType()

◆ GetOpaqueMetadata()

◆ SetOpaqueMetadata()

◆ CountBuckets()

◆ CountUsedBuckets()

◆ GetUpdateMode()

◆ SetUpdateModeAppending()

◆ ImportFromFileForward() [1/2]

◆ ImportFromFileForward() [2/2]

◆ ImportFromFileBackward() [1/2]

◆ ImportFromFileBackward() [2/2]

◆ ValidateHashBuckets()

◆ ValidateRecords()

◆ ReadMetadata()

◆ FindRecordBase()

◆ GetCRCWidthFromStaticFlags()

◆ MakeCompressorFromStaticFlags()

◆ CheckRecordCompressionModeIsSupported()

◆ RestoreDatabase()

Member Data Documentation

◆ DEFAULT_OFFSET_WIDTH

◆ DEFAULT_ALIGN_POW

◆ DEFAULT_NUM_BUCKETS

◆ DEFAULT_FBP_CAPACITY

◆ DEFAULT_MIN_READ_SIZE

◆ OPAQUE_METADATA_SIZE