Tkrzw-RPC
|
RPC interface to access the database service via gRPC protocol. More...
#include <tkrzw_dbm_remote.h>
Classes | |
class | Iterator |
Iterator for each record. More... | |
struct | ReplicateLog |
Wrapper of an update log for replication. More... | |
class | Replicator |
Reader for update logs for asynchronous replicatoin. More... | |
class | Stream |
Stream for better performance of intensive operations. More... | |
Public Member Functions | |
RemoteDBM () | |
Constructor. More... | |
~RemoteDBM () | |
Destructor. More... | |
RemoteDBM (const RemoteDBM &rhs)=delete | |
Copy and assignment are disabled. More... | |
RemoteDBM & | operator= (const RemoteDBM &rhs)=delete |
void | InjectStub (void *stub) |
Injects a stub for testing. More... | |
Status | Connect (const std::string &address, double timeout=-1, const std::string &auth_config="") |
Connects to the server. More... | |
Status | Disconnect () |
Disconnects the connection to the server. More... | |
Status | SetDBMIndex (int32_t dbm_index) |
Sets the index of the DBM to access. More... | |
Status | Echo (std::string_view message, std::string *echo) |
Sends a message and gets back the echo message. More... | |
Status | Inspect (std::vector< std::pair< std::string, std::string >> *records) |
Inspects a database. More... | |
Status | Get (std::string_view key, std::string *value=nullptr) |
Gets the value of a record of a key. More... | |
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... | |
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... | |
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... | |
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... | |
Status | Set (std::string_view key, std::string_view value, bool overwrite=true) |
Sets a record of a key and a value. More... | |
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... | |
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... | |
Status | SetMulti (const std::map< std::string, std::string > &records, bool overwrite=true) |
Sets multiple records, with a map of strings. More... | |
Status | Remove (std::string_view key) |
Removes a record of a key. More... | |
Status | RemoveMulti (const std::vector< std::string_view > &keys) |
Removes records of keys, with a string view vector. More... | |
Status | RemoveMulti (const std::initializer_list< std::string_view > &keys) |
Removes records of keys, with an initializer list. More... | |
Status | RemoveMulti (const std::vector< std::string > &keys) |
Removes records of keys, with a string vector. More... | |
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... | |
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... | |
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... | |
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... | |
Status | CompareExchange (std::string_view key, std::string_view expected, std::string_view desired, std::string *actual=nullptr, bool *found=nullptr, double retry_wait=0, bool notify=false) |
Compares the value of a record and exchanges if the condition meets. More... | |
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... | |
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... | |
Status | Rekey (std::string_view old_key, std::string_view new_key, bool overwrite=true, bool copying=false) |
Changes the key of a record. More... | |
Status | PopFirst (std::string *key=nullptr, std::string *value=nullptr, double retry_wait=0) |
Gets the first record and removes it. More... | |
Status | PushLast (std::string_view value, double wtime=-1, bool notify=false) |
Adds a record with a key of the current timestamp. More... | |
Status | Count (int64_t *count) |
Gets the number of records. More... | |
int64_t | CountSimple () |
Gets the number of records, in a simple way. More... | |
Status | GetFileSize (int64_t *size) |
Gets the current file size of the database. More... | |
int64_t | GetFileSizeSimple () |
Gets the current file size of the database, in a simple way. More... | |
Status | Clear () |
Removes all records. More... | |
Status | Rebuild (const std::map< std::string, std::string > ¶ms={}) |
Rebuilds the entire database. More... | |
Status | ShouldBeRebuilt (bool *tobe) |
Checks whether the database should be rebuilt. More... | |
Status | Synchronize (bool hard, const std::map< std::string, std::string > ¶ms={}) |
Synchronizes the content of the database to the file system. More... | |
Status | Search (std::string_view mode, std::string_view pattern, std::vector< std::string > *matched, size_t capacity=0) |
Searches a database and get keys which match a pattern, according to a mode expression. More... | |
Status | ChangeMaster (std::string_view master, double timestamp_skew=0) |
Changes the master server of the replication. More... | |
std::unique_ptr< Stream > | MakeStream () |
Makes a stream for intensive operations. More... | |
std::unique_ptr< Iterator > | MakeIterator () |
Makes an iterator for each record. More... | |
std::unique_ptr< Replicator > | MakeReplicator () |
Makes a replicator for asynchronous replication. More... | |
RPC interface to access the database service via gRPC protocol.
All operations are thread-safe; Multiple threads can access the same connection concurrently. The SetDBMIndex affects all threads so it should be called before the object is shared.
tkrzw::RemoteDBM::RemoteDBM | ( | ) |
Constructor.
tkrzw::RemoteDBM::~RemoteDBM | ( | ) |
Destructor.
|
explicitdelete |
Copy and assignment are disabled.
void tkrzw::RemoteDBM::InjectStub | ( | void * | stub | ) |
Injects a stub for testing.
stub | The pointer to the DBMService::StubInterface object. The ownership is taken. |
This method is used instead of the Connect method. With this, you can inject mock stubs for testing and any kind of stubs with arbitrary auth/network settings.
Status tkrzw::RemoteDBM::Connect | ( | const std::string & | address, |
double | timeout = -1 , |
||
const std::string & | auth_config = "" |
||
) |
Connects to the server.
address | The address or the host name of the server and its port number. For IPv4 address, it's like "127.0.0.1:1978". For IPv6, it's like "[::1]:1978". For UNIX domain sockets, it's like "unix:/path/to/file". |
timeout | The timeout in seconds for connection and each operation. Negative means unlimited. |
auth_config | The authentication configuration. It it is empty, no authentication is done. If it begins with "ssl:", the SSL authentication is done. Key-value parameters in "key=value,key=value,..." format comes next. For SSL, "key", "cert", and "root" parameters specify the paths of the client private key file, the client certificate file, and the root CA certificate file respectively. |
Status tkrzw::RemoteDBM::Disconnect | ( | ) |
Disconnects the connection to the server.
Status tkrzw::RemoteDBM::SetDBMIndex | ( | int32_t | dbm_index | ) |
Sets the index of the DBM to access.
dbm_index | The index of the DBM to access. |
Status tkrzw::RemoteDBM::Echo | ( | std::string_view | message, |
std::string * | echo | ||
) |
Sends a message and gets back the echo message.
message | The message to send. |
echo | The pointer to a string object to contain the echo message. |
Status tkrzw::RemoteDBM::Inspect | ( | std::vector< std::pair< std::string, std::string >> * | records | ) |
Inspects a database.
records | The pointer to a map to store retrieved records. |
If the DBM index is negative, basic metadata of all DBMs are obtained.
Status tkrzw::RemoteDBM::Get | ( | std::string_view | key, |
std::string * | value = nullptr |
||
) |
Gets the value of a record of a key.
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. |
std::string tkrzw::RemoteDBM::GetSimple | ( | std::string_view | key, |
std::string_view | default_value = "" |
||
) |
Gets the value of a record of a key, in a simple way.
key | The key of the record. |
default_value | The value to be returned on failure. |
Status tkrzw::RemoteDBM::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.
keys | The keys of records to retrieve. |
records | The pointer to a map to store retrieved records. Keys which don't match existing records are ignored. |
Status tkrzw::RemoteDBM::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.
keys | The keys of records to retrieve. |
records | The pointer to a map to store retrieved records. Keys which don't match existing records are ignored. |
Status tkrzw::RemoteDBM::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.
keys | The keys of records to retrieve. |
records | The pointer to a map to store retrieved records. Keys which don't match existing records are ignored. |
Status tkrzw::RemoteDBM::Set | ( | std::string_view | key, |
std::string_view | value, | ||
bool | overwrite = true |
||
) |
Sets a record of a key and a value.
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. |
Status tkrzw::RemoteDBM::SetMulti | ( | const std::map< std::string_view, std::string_view > & | records, |
bool | overwrite = true |
||
) |
Sets multiple records, with a map of string views.
records | The records to store. |
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. |
Status tkrzw::RemoteDBM::SetMulti | ( | const std::initializer_list< std::pair< std::string_view, std::string_view >> & | records, |
bool | overwrite = true |
||
) |
Sets multiple records, with an initializer list.
records | The records to store. |
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. |
Status tkrzw::RemoteDBM::SetMulti | ( | const std::map< std::string, std::string > & | records, |
bool | overwrite = true |
||
) |
Sets multiple records, with a map of strings.
records | The records to store. |
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. |
Status tkrzw::RemoteDBM::Remove | ( | std::string_view | key | ) |
Removes a record of a key.
key | The key of the record. |
Status tkrzw::RemoteDBM::RemoveMulti | ( | const std::vector< std::string_view > & | keys | ) |
Removes records of keys, with a string view vector.
keys | The keys of records to remove. |
Status tkrzw::RemoteDBM::RemoveMulti | ( | const std::initializer_list< std::string_view > & | keys | ) |
Removes records of keys, with an initializer list.
keys | The keys of records to remove. |
Status tkrzw::RemoteDBM::RemoveMulti | ( | const std::vector< std::string > & | keys | ) |
Removes records of keys, with a string vector.
keys | The keys of records to remove. |
Status tkrzw::RemoteDBM::Append | ( | std::string_view | key, |
std::string_view | value, | ||
std::string_view | delim = "" |
||
) |
Appends data at the end of a record of a key.
key | The key of the record. |
value | The value to append. |
delim | The delimiter to put after the existing record. |
If there's no existing record, the value is set without the delimiter.
Status tkrzw::RemoteDBM::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.
records | The records to append. |
delim | The delimiter to put after the existing record. |
If there's no existing record, the value is set without the delimiter.
Status tkrzw::RemoteDBM::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.
records | The records to store. |
delim | The delimiter to put after the existing record. |
If there's no existing record, the value is set without the delimiter.
Status tkrzw::RemoteDBM::AppendMulti | ( | const std::map< std::string, std::string > & | records, |
std::string_view | delim = "" |
||
) |
Appends data to multiple records, with a map of strings.
records | The records to append. |
delim | The delimiter to put after the existing record. |
If there's no existing record, the value is set without the delimiter.
Status tkrzw::RemoteDBM::CompareExchange | ( | std::string_view | key, |
std::string_view | expected, | ||
std::string_view | desired, | ||
std::string * | actual = nullptr , |
||
bool * | found = nullptr , |
||
double | retry_wait = 0 , |
||
bool | notify = false |
||
) |
Compares the value of a record and exchanges if the condition meets.
key | The key of the record. |
expected | The expected value. If the data is nullptr, no existing record is expected. If it is DBM::ANY_DATA, an existing record with any value is expacted. |
desired | The desired value. If the data is nullptr, the record is to be removed. If it is DBM::ANY_DATA, no update is done. |
actual | The pointer to a string object to contain the actual value of the existing record. If it is nullptr, it is ignored. |
found | The pointer to a variable to contain whether there is an existing record. If it is nullptr, it is ignored. |
retry_wait | The maximum wait time in seconds before retrying. If it is zero, no retry is done. If it is positive, retry is done after waiting for the notifications of the next update for the time at most. |
notify | If true, a notification signal is sent to wake up retrying threads. |
Status tkrzw::RemoteDBM::Increment | ( | std::string_view | key, |
int64_t | increment = 1 , |
||
int64_t * | current = nullptr , |
||
int64_t | initial = 0 |
||
) |
Increments the numeric value of a record.
key | The key of the record. |
increment | The incremental value. If it is INT64MIN, the current value is not changed and a new record is not created. |
current | The pointer to an integer to contain the current value. If it is nullptr, it is ignored. |
initial | The initial value. |
The record value is stored as an 8-byte big-endian integer. Negative is also supported.
int64_t tkrzw::RemoteDBM::IncrementSimple | ( | std::string_view | key, |
int64_t | increment = 1 , |
||
int64_t | initial = 0 |
||
) |
Increments the numeric value of a record, in a simple way.
key | The key of the record. |
increment | The incremental value. |
initial | The initial value. |
The record value is treated as a decimal integer. Negative is also supported.
Status tkrzw::RemoteDBM::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.
expected | The record keys and their expected values. If the value is nullptr, no existing record is expected. If the value is DBM::ANY_DATA, an existing record with any value is expacted. |
desired | The record keys and their desired values. If the value is nullptr, the record is to be removed. |
Status tkrzw::RemoteDBM::Rekey | ( | std::string_view | old_key, |
std::string_view | new_key, | ||
bool | overwrite = true , |
||
bool | copying = false |
||
) |
Changes the key of a record.
old_key | The old key of the record. |
new_key | The new key of the record. |
overwrite | Whether to overwrite the existing record of the new key. |
copying | Whether to retain the record of the old key. |
Status tkrzw::RemoteDBM::PopFirst | ( | std::string * | key = nullptr , |
std::string * | value = nullptr , |
||
double | retry_wait = 0 |
||
) |
Gets the first record and removes it.
key | The pointer to a string object to contain the key of the first record. If it is nullptr, it is ignored. |
value | The pointer to a string object to contain the value of the first record. If it is nullptr, it is ignored. |
retry_wait | The maximum wait time in seconds before retrying. If it is zero, no retry is done. If it is positive, retry is done after waiting for the notifications of the next update for the time at most. |
Status tkrzw::RemoteDBM::PushLast | ( | std::string_view | value, |
double | wtime = -1 , |
||
bool | notify = false |
||
) |
Adds a record with a key of the current timestamp.
value | The value of the record. |
wtime | The current wall time used to generate the key. If it is negative, the system clock is used. |
notify | If true, notification signal is sent. |
The key is generated as an 8-bite big-endian binary string of the timestamp. If there is an existing record matching the generated key, the key is regenerated and the attempt is repeated until it succeeds.
Status tkrzw::RemoteDBM::Count | ( | int64_t * | count | ) |
Gets the number of records.
count | The pointer to an integer object to contain the result count. |
int64_t tkrzw::RemoteDBM::CountSimple | ( | ) |
Gets the number of records, in a simple way.
Status tkrzw::RemoteDBM::GetFileSize | ( | int64_t * | size | ) |
Gets the current file size of the database.
size | The pointer to an integer object to contain the result size. |
int64_t tkrzw::RemoteDBM::GetFileSizeSimple | ( | ) |
Gets the current file size of the database, in a simple way.
Status tkrzw::RemoteDBM::Clear | ( | ) |
Removes all records.
Status tkrzw::RemoteDBM::Rebuild | ( | const std::map< std::string, std::string > & | params = {} | ) |
Rebuilds the entire database.
params | Optional parameters. |
Tuning options can be given by the optional parameters, as with the Open method of the PolyDBM class and the database configurations of the server command. A unset parameter means that the current setting is succeeded or calculated implicitly.
In addition, HashDBM, TreeDBM, and SkipDBM supports the following parameters.
Status tkrzw::RemoteDBM::ShouldBeRebuilt | ( | bool * | tobe | ) |
Checks whether the database should be rebuilt.
tobe | The pointer to a boolean object to contain the result decision. |
Status tkrzw::RemoteDBM::Synchronize | ( | bool | hard, |
const std::map< std::string, std::string > & | params = {} |
||
) |
Synchronizes the content of the database to the file system.
hard | True to do physical synchronization with the hardware or false to do only logical synchronization with the file system. |
params | Optional parameters. |
The "reducer" parameter specifies the reducer for SkipDBM. "ReduceToFirst", "ReduceToSecond", "ReduceToLast", etc are supported. If the parameter "make_backup" exists, a backup file is created in the same directory as the database file. The backup file name has a date suffix in GMT, like ".backup.20210831213749". If the value of "make_backup" not empty, it is the value is used as the suffix.
Status tkrzw::RemoteDBM::Search | ( | std::string_view | mode, |
std::string_view | pattern, | ||
std::vector< std::string > * | matched, | ||
size_t | capacity = 0 |
||
) |
Searches a database and get keys which match a pattern, according to a mode expression.
mode | The search mode. "contain" extracts keys containing the pattern. "begin" extracts keys beginning with the pattern. "end" extracts keys ending with the pattern. "regex" extracts keys partially matches the pattern of a regular expression. "edit" extracts keys whose edit distance to the UTF-8 pattern is the least. "editbin" extracts keys whose edit distance to the binary pattern is the least. Ordered databases support "upper" and "lower" which extract keys whose positions are upper/lower than the pattern. "upperinc" and "lowerinc" are their inclusive versions. |
pattern | The pattern for matching. |
matched | A vector to contain the result. |
capacity | The maximum records to obtain. 0 means unlimited. |
Status tkrzw::RemoteDBM::ChangeMaster | ( | std::string_view | master, |
double | timestamp_skew = 0 |
||
) |
Changes the master server of the replication.
master | The address of the master server. If it is empty, replication stops. |
timestamp_skew | The timestamp skew in milliseconds. Negative makes the timestamp back to the past. |
std::unique_ptr<Stream> tkrzw::RemoteDBM::MakeStream | ( | ) |
Makes a stream for intensive operations.
std::unique_ptr<Iterator> tkrzw::RemoteDBM::MakeIterator | ( | ) |
Makes an iterator for each record.
std::unique_ptr<Replicator> tkrzw::RemoteDBM::MakeReplicator | ( | ) |
Makes a replicator for asynchronous replication.