...
▽
Run Format

Package tkrzw_rpc

import "github.com/estraier/tkrzw-rpc-go"
Overview
Index

Overview ▾

Go client library of Tkrzw-RPC

The core package of Tkrzw-RPC provides a server program which manages databases of Tkrzw. This package provides a Python client library to access the service via gRPC protocol. Tkrzw is a library to mange key-value storages in various algorithms. With Tkrzw, the application can handle database files efficiently in process without any network overhead. However, it means that multiple processes cannot open the same database file simultaneously. Tkrzw-RPC solves the issue by using a server program which manages database files and allowing other processes access the contents via RPC.

The class "RemoteDBM" has a similar API to the local DBM API, which represents an associative array aka a map[[]byte][]byte in Go. Read the homepage https://dbmx.net/tkrzw-rpc/ for details.

All identifiers are defined under the package "tkrzw_rpc", which can be imported in source files of application programs as "github.com/estraier/tkrzw-rpc-go". 

import "github.com/estraier/tkrzw-rpc-go"

An instance of the struct "RemoteDBM" is used in order to handle a database connection. You can store, delete, and retrieve records with the instance. The result status of each operation is represented by an object of the struct "Status". Iterator to access each record is implemented by the struct "Iterator".

The key and the value of the records are stored as byte arrays. However, you can specify strings and other types which imlements the Stringer interface whereby the object is converted into a byte array.

If you write the above import directive and prepare the "go.mod" file, the Go module for Tkrzw-RPC is installed implicitly when you run "go get". Go 1.14 or later is required to use this package.

The following code is a simple example to use a database, without checking errors. Many methods accept both byte arrays and strings. If strings are given, they are converted implicitly into byte arrays. 

package main

import (
  "fmt"
  "github.com/estraier/tkrzw-rpc-go"
)

func main() {
  // Prepares the database.
  dbm := tkrzw_rpc.NewRemoteDBM()
  dbm.Connect("127.0.0.1:1978", -1, "")

  // Sets records.
  // Keys and values are implicitly converted into bytes.
  dbm.Set("first", "hop", true)
  dbm.Set("second", "step", true)
  dbm.Set("third", "jump", true)

  // Retrieves record values as strings.
  fmt.Println(dbm.GetStrSimple("first", "*"))
  fmt.Println(dbm.GetStrSimple("second", "*"))
  fmt.Println(dbm.GetStrSimple("third", "*"))

  // Checks and deletes a record.
  if dbm.Check("first") {
    dbm.Remove("first")
  }

  // Traverses records with a range over a channel.
  for record := range dbm.EachStr() {
    fmt.Println(record.Key, record.Value)
  }

  // Closes the connection.
  dbm.Disconnect()
}

The following code is an advanced example where a so-called long transaction is done by the compare-and-exchange (aka compare-and-swap) idiom. The example also shows how to use the iterator to access each record. 

package main

import (
  "fmt"
  "github.com/estraier/tkrzw-rpc-go"
)

func main() {
  // Prepares the database.
  // The timeout is in seconds.
  // The method OrDie causes panic if the status is not success.
  // You should write your own error handling in large scale programs.
  dbm := tkrzw_rpc.NewRemoteDBM()
  dbm.Connect("localhost:1978", 10, "").OrDie()

  // Closes the connection for sure and checks the error too.
  defer func() { dbm.Disconnect().OrDie() }()

  // Two bank accounts for Bob and Alice.
  // Numeric values are converted into strings implicitly.
  dbm.Set("Bob", 1000, false).OrDie()
  dbm.Set("Alice", 3000, false).OrDie()

  // Function to do a money transfer atomically.
  transfer := func(src_key string, dest_key string, amount int64) *tkrzw_rpc.Status {
    // Gets the old values as numbers.
    old_src_value := tkrzw_rpc.ToInt(dbm.GetStrSimple(src_key, "0"))
    old_dest_value := tkrzw_rpc.ToInt(dbm.GetStrSimple(dest_key, "0"))

    // Calculates the new values.
    new_src_value := old_src_value - amount
    new_dest_value := old_dest_value + amount
    if new_src_value < 0 {
      return tkrzw_rpc.NewStatus(tkrzw_rpc.StatusApplicationError, "insufficient value")
    }

    // Prepares the pre-condition and the post-condition of the transaction.
    old_records := []tkrzw_rpc.KeyValueStrPair{
      {src_key, tkrzw_rpc.ToString(old_src_value)},
      {dest_key, tkrzw_rpc.ToString(old_dest_value)},
    }
    new_records := []tkrzw_rpc.KeyValueStrPair{
      {src_key, tkrzw_rpc.ToString(new_src_value)},
      {dest_key, tkrzw_rpc.ToString(new_dest_value)},
    }

    // Performs the transaction atomically.
    // This fails safely if other concurrent transactions break the pre-condition.
    return dbm.CompareExchangeMultiStr(old_records, new_records)
  }

  // Tries a transaction until it succeeds
  var status *tkrzw_rpc.Status
  for num_tries := 0; num_tries < 100; num_tries++ {
    status = transfer("Alice", "Bob", 500)
    if !status.Equals(tkrzw_rpc.StatusInfeasibleError) {
      break
    }
  }
  status.OrDie()

  // Traverses records in a primitive way.
  iter := dbm.MakeIterator()
  defer iter.Destruct()
  iter.First()
  for {
    key, value, status := iter.GetStr()
    if !status.IsOK() {
      break
    }
    fmt.Println(key, value)
    iter.Next()
  }
}

Index ▾

Constants
Variables
func IsAnyBytes(data []byte) bool
func IsAnyData(data interface{}) bool
func IsAnyString(data string) bool
func IsNilData(data interface{}) bool
func IsNilString(data string) bool
func ParseParams(expr string) map[string]string
func StatusCodeName(code StatusCode) string
func ToByteArray(x interface{}) []byte
func ToFloat(value interface{}) float64
func ToInt(value interface{}) int64
func ToString(x interface{}) string
type Iterator
    func (self *Iterator) Destruct()
    func (self *Iterator) First() *Status
    func (self *Iterator) Get() ([]byte, []byte, *Status)
    func (self *Iterator) GetKey() ([]byte, *Status)
    func (self *Iterator) GetKeyStr() (string, *Status)
    func (self *Iterator) GetStr() (string, string, *Status)
    func (self *Iterator) GetValue() ([]byte, *Status)
    func (self *Iterator) GetValueStr() (string, *Status)
    func (self *Iterator) Jump(key interface{}) *Status
    func (self *Iterator) JumpLower(key interface{}, inclusive bool) *Status
    func (self *Iterator) JumpUpper(key interface{}, inclusive bool) *Status
    func (self *Iterator) Last() *Status
    func (self *Iterator) Next() *Status
    func (self *Iterator) Previous() *Status
    func (self *Iterator) Remove() *Status
    func (self *Iterator) Set(value interface{}) *Status
    func (self *Iterator) Step() ([]byte, []byte, *Status)
    func (self *Iterator) StepStr() (string, string, *Status)
    func (self *Iterator) String() string
type KeyValuePair
type KeyValueStrPair
type RemoteDBM
    func NewRemoteDBM() *RemoteDBM
    func (self *RemoteDBM) Append(key interface{}, value interface{}, delim interface{}) *Status
    func (self *RemoteDBM) AppendMulti(records map[string][]byte, delim interface{}) *Status
    func (self *RemoteDBM) AppendMultiStr(records map[string]string, delim interface{}) *Status
    func (self *RemoteDBM) Check(key interface{}) bool
    func (self *RemoteDBM) Clear() *Status
    func (self *RemoteDBM) CompareExchange(key interface{}, expected interface{}, desired interface{}) *Status
    func (self *RemoteDBM) CompareExchangeAdvanced(key interface{}, expected interface{}, desired interface{}, retryWait float64, notify bool) ([]byte, *Status)
    func (self *RemoteDBM) CompareExchangeAdvancedStr(key interface{}, expected interface{}, desired interface{}, retryWait float64, notify bool) (string, *Status)
    func (self *RemoteDBM) CompareExchangeMulti(expected []KeyValuePair, desired []KeyValuePair) *Status
    func (self *RemoteDBM) CompareExchangeMultiStr(expected []KeyValueStrPair, desired []KeyValueStrPair) *Status
    func (self *RemoteDBM) Connect(address string, timeout float64, auth_config string) *Status
    func (self *RemoteDBM) Count() (int64, *Status)
    func (self *RemoteDBM) CountSimple() int64
    func (self *RemoteDBM) Disconnect() *Status
    func (self *RemoteDBM) Each() <-chan KeyValuePair
    func (self *RemoteDBM) EachStr() <-chan KeyValueStrPair
    func (self *RemoteDBM) Echo(message string) (string, *Status)
    func (self *RemoteDBM) Get(key interface{}) ([]byte, *Status)
    func (self *RemoteDBM) GetFileSize() (int64, *Status)
    func (self *RemoteDBM) GetFileSizeSimple() int64
    func (self *RemoteDBM) GetMulti(keys []string) map[string][]byte
    func (self *RemoteDBM) GetMultiStr(keys []string) map[string]string
    func (self *RemoteDBM) GetSimple(key interface{}, defaultValue interface{}) []byte
    func (self *RemoteDBM) GetStr(key interface{}) (string, *Status)
    func (self *RemoteDBM) GetStrSimple(key interface{}, defaultValue interface{}) string
    func (self *RemoteDBM) Increment(key interface{}, inc interface{}, init interface{}) (int64, *Status)
    func (self *RemoteDBM) Inspect() map[string]string
    func (self *RemoteDBM) MakeIterator() *Iterator
    func (self *RemoteDBM) PopFirst(retryWait float64) ([]byte, []byte, *Status)
    func (self *RemoteDBM) PopFirstStr(retryWait float64) (string, string, *Status)
    func (self *RemoteDBM) PushLast(value interface{}, wtime float64, notify bool) *Status
    func (self *RemoteDBM) Rebuild(params map[string]string) *Status
    func (self *RemoteDBM) Rekey(oldKey interface{}, newKey interface{}, overwrite bool, copying bool) *Status
    func (self *RemoteDBM) Remove(key interface{}) *Status
    func (self *RemoteDBM) RemoveMulti(keys []string) *Status
    func (self *RemoteDBM) Search(mode string, pattern string, capacity int) []string
    func (self *RemoteDBM) Set(key interface{}, value interface{}, overwrite bool) *Status
    func (self *RemoteDBM) SetDBMIndex(dbmIndex int32) *Status
    func (self *RemoteDBM) SetMulti(records map[string][]byte, overwrite bool) *Status
    func (self *RemoteDBM) SetMultiStr(records map[string]string, overwrite bool) *Status
    func (self *RemoteDBM) ShouldBeRebuilt() (bool, *Status)
    func (self *RemoteDBM) ShouldBeRebuiltSimple() bool
    func (self *RemoteDBM) String() string
    func (self *RemoteDBM) Synchronize(hard bool, params map[string]string) *Status
type Status
    func NewStatus(args ...interface{}) *Status
    func NewStatus1(code StatusCode) *Status
    func NewStatus2(code StatusCode, message string) *Status
    func (self *Status) Equals(rhs interface{}) bool
    func (self *Status) Error() string
    func (self *Status) GetCode() StatusCode
    func (self *Status) GetMessage() string
    func (self *Status) IsOK() bool
    func (self *Status) Join(rhs *Status)
    func (self *Status) OrDie()
    func (self *Status) Set(args ...interface{})
    func (self *Status) String() string
type StatusCode

Package files

doc.go iterator.go remote_dbm.go status.go util.go

Constants

Enumeration of status codes. 

const (
    // Success.
    StatusSuccess = StatusCode(0)
    // Generic error whose cause is unknown.
    StatusUnknownError = StatusCode(1)
    // Generic error from underlying systems.
    StatusSystemError = StatusCode(2)
    // Error that the feature is not implemented.
    StatusNotImplementedError = StatusCode(3)
    // Error that a precondition is not met.
    StatusPreconditionError = StatusCode(4)
    // Error that a given argument is invalid.
    StatusInvalidArgumentError = StatusCode(5)
    // Error that the operation is canceled.
    StatusCanceledError = StatusCode(6)
    // Error that a specific resource is not found.
    StatusNotFoundError = StatusCode(7)
    // Error that the operation is not permitted.
    StatusPermissionError = StatusCode(8)
    // Error that the operation is infeasible.
    StatusInfeasibleError = StatusCode(9)
    // Error that a specific resource is duplicated.
    StatusDuplicationError = StatusCode(10)
    // Error that internal data are broken.
    StatusBrokenDataError = StatusCode(11)
    // Error caused by networking failure.
    StatusNetworkError = StatusCode(12)
    // Generic error caused by the application logic.
    StatusApplicationError = StatusCode(13)
)

Variables

The special bytes value for no-operation or any data. 

var AnyBytes = []byte("\x00[ANY]\x00")

The special string value for no-operation or any data. 

var AnyString = string([]byte("\x00[ANY]\x00"))

The special string value for non-existing data. 

var NilString = string([]byte("\x00[NIL]\x00"))

func IsAnyBytes 

func IsAnyBytes(data []byte) bool

Checks whether the given bytes are the any bytes.

@param data The data to check.
@return True if the data are the any bytes.

func IsAnyData 

func IsAnyData(data interface{}) bool

Checks whether the given data is a unique value of any data.

@param data The data to check.
@return True if the data is any data or, false if not.

func IsAnyString 

func IsAnyString(data string) bool

Checks whether the given string is the any string.

@param data The data to check.
@return True if the data is the string, or false if not.

func IsNilData 

func IsNilData(data interface{}) bool

Checks whether the given data is a nil-equivalent value.

@param data The data to check.
@return True if the data is a nil-equivalent value, or false if not.

func IsNilString 

func IsNilString(data string) bool

Checks whether the given string is the nil string.

@param data The data to check.
@return True if the data is the nil string, or false if not.

func ParseParams 

func ParseParams(expr string) map[string]string

Parses a parameter string to make a parameter string map.

@param expr A parameter string in "name=value,name=value,..." format.
@return The string map of the parameters.

func StatusCodeName 

func StatusCodeName(code StatusCode) string

Gets the name of a status code.

@param code The status code.
@return The name of the status code.

func ToByteArray 

func ToByteArray(x interface{}) []byte

Converts any object into a byte array.

@param x The object to convert.
@return The result byte array.

func ToFloat 

func ToFloat(value interface{}) float64

Converts any object into a real number.

@param x The object to convert.
@return The result real number.

func ToInt 

func ToInt(value interface{}) int64

Converts any object into an integer.

@param x The object to convert.
@return The result integer.

func ToString 

func ToString(x interface{}) string

Converts any object into a string.

@param x The object to convert.
@return The result string.

type Iterator

Iterator for each record.

An iterator is made by the "MakeIerator" method of RemoteDBM. Every unused iterator object should be destructed explicitly by the "Destruct" method to free resources. 

type Iterator struct {
    // contains filtered or unexported fields
}

func (*Iterator) Destruct 

func (self *Iterator) Destruct()

Releases the resource explicitly.

func (*Iterator) First 

func (self *Iterator) First() *Status

Initializes the iterator to indicate the first record.

@return The result status.

Even if there's no record, the operation doesn't fail.

func (*Iterator) Get 

func (self *Iterator) Get() ([]byte, []byte, *Status)

Gets the key and the value of the current record of the iterator.

@return The key and the value of the current record, and the result status.

func (*Iterator) GetKey 

func (self *Iterator) GetKey() ([]byte, *Status)

Gets the key of the current record.

@return The key of the current record and the result status.

func (*Iterator) GetKeyStr 

func (self *Iterator) GetKeyStr() (string, *Status)

Gets the key of the current record, as a string.

@return The key of the current record and the result status.

func (*Iterator) GetStr 

func (self *Iterator) GetStr() (string, string, *Status)

Gets the key and the value of the current record of the iterator, as strings.

@return The key and the value of the current record, and the result status.

func (*Iterator) GetValue 

func (self *Iterator) GetValue() ([]byte, *Status)

Gets the value of the current record.

@return The value of the current record and the result status.

func (*Iterator) GetValueStr 

func (self *Iterator) GetValueStr() (string, *Status)

Gets the value of the current record, as a string.

@return The value of the current record and the result status.

func (*Iterator) Jump 

func (self *Iterator) Jump(key interface{}) *Status

Initializes the iterator to indicate a specific record.

@param key The key of the record to look for.
@return The result status.

Ordered databases can support "lower bound" jump; If there's no record with the same key, the iterator refers to the first record whose key is greater than the given key. The operation fails with unordered databases if there's no record with the same key.

func (*Iterator) JumpLower 

func (self *Iterator) JumpLower(key interface{}, inclusive bool) *Status

Initializes the iterator to indicate the last record whose key is lower than a given key.

@param key The key to compare with.
@param inclusive If true, the considtion is inclusive: equal to or lower than the key.
@return The result status.

Even if there's no matching record, the operation doesn't fail. This method is suppoerted only by ordered databases.

func (*Iterator) JumpUpper 

func (self *Iterator) JumpUpper(key interface{}, inclusive bool) *Status

Initializes the iterator to indicate the first record whose key is upper than a given key.

@param key The key to compare with.
@param inclusive If true, the considtion is inclusive: equal to or upper than the key.
@return The result status.

Even if there's no matching record, the operation doesn't fail. This method is suppoerted only by ordered databases.

func (*Iterator) Last 

func (self *Iterator) Last() *Status

Initializes the iterator to indicate the last record.

@return The result status.

Even if there's no record, the operation doesn't fail. This method is suppoerted only by ordered databases.

func (*Iterator) Next 

func (self *Iterator) Next() *Status

Moves the iterator to the next record.

@return The result status.

If the current record is missing, the operation fails. Even if there's no next record, the operation doesn't fail.

func (*Iterator) Previous 

func (self *Iterator) Previous() *Status

Moves the iterator to the previous record.

@return The result status.

If the current record is missing, the operation fails. Even if there's no previous record, the operation doesn't fail. This method is suppoerted only by ordered databases.

func (*Iterator) Remove 

func (self *Iterator) Remove() *Status

Removes the current record.

@return The result status.

func (*Iterator) Set 

func (self *Iterator) Set(value interface{}) *Status

Sets the value of the current record.

@param value The value of the record.
@return The result status.

func (*Iterator) Step 

func (self *Iterator) Step() ([]byte, []byte, *Status)

Gets the current record and moves the iterator to the next record.

@return The key and the value of the current record, and the result status.

func (*Iterator) StepStr 

func (self *Iterator) StepStr() (string, string, *Status)

Gets the current record and moves the iterator to the next record, as strings.

@return The key and the value of the current record, and the result status.

func (*Iterator) String 

func (self *Iterator) String() string

Makes a string representing the iterator.

@return The string representing the iterator.

type KeyValuePair

A pair of the key and the value of a record. 

type KeyValuePair struct {
    // The key.
    Key []byte
    // The value
    Value []byte
}

type KeyValueStrPair

A string pair of the key and the value of a record. 

type KeyValueStrPair struct {
    // The key.
    Key string
    // The value
    Value string
}

type RemoteDBM

Remote database manager.

All operations except for "Connect" and "Disconnect" are thread-safe; Multiple threads can access the same database concurrently. The "SetDBMIndex" affects all threads so it should be called before the object is shared. 

type RemoteDBM struct {
    // contains filtered or unexported fields
}

func NewRemoteDBM 

func NewRemoteDBM() *RemoteDBM

Makes a new RemoteDBM object.

@return The pointer to the created remote database object.

func (*RemoteDBM) Append 

func (self *RemoteDBM) Append(key interface{}, value interface{}, delim interface{}) *Status

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

@param key The key of the record.
@param value The value to append.
@param delim The delimiter to put after the existing record.
@return The result status.

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

func (*RemoteDBM) AppendMulti 

func (self *RemoteDBM) AppendMulti(records map[string][]byte, delim interface{}) *Status

Appends data to multiple records.

@param records Records to append.
@param delim The delimiter to put after the existing record.
@return The result status.

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

func (*RemoteDBM) AppendMultiStr 

func (self *RemoteDBM) AppendMultiStr(records map[string]string, delim interface{}) *Status

Appends data to multiple records, with string data.

@param records Records to append.
@param delim The delimiter to put after the existing record.
@return The result status.

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

func (*RemoteDBM) Check 

func (self *RemoteDBM) Check(key interface{}) bool

Checks if a record exists or not.

@param key The key of the record.
@return True if the record exists, or false if not.

func (*RemoteDBM) Clear 

func (self *RemoteDBM) Clear() *Status

Removes all records.

@return The result status.

func (*RemoteDBM) CompareExchange 

func (self *RemoteDBM) CompareExchange(
    key interface{}, expected interface{}, desired interface{}) *Status

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

@param key The key of the record.
@param expected The expected value. If it is nil or NilString, no existing record is expected. If it is AnyBytes or AnyString, an existing record with any value is expacted.
@param desired The desired value. If it is nil or NilString, the record is to be removed. If it is AnyBytes or AnyString, no update is done.
@return The result status. If the condition doesn't meet, StatusInfeasibleError is returned.

func (*RemoteDBM) CompareExchangeAdvanced 

func (self *RemoteDBM) CompareExchangeAdvanced(
    key interface{}, expected interface{}, desired interface{},
    retryWait float64, notify bool) ([]byte, *Status)

Does compare-and-exchange and/or gets the old value of the record.

@param key The key of the record.
@param expected The expected value. If it is nil or NilString, no existing record is expected. If it is AnyBytes or AnyString, an existing record with any value is expacted.
@param desired The desired value. If it is nil or NilString, the record is to be removed. If it is AnyBytes or AnyString, no update is done.
@param retryWait 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.
@param notify If true, a notification signal is sent to wake up retrying threads.
@return The old value and the result status. If the condition doesn't meet, the state is INFEASIBLE_ERROR. If there's no existing record, the value is nil.

func (*RemoteDBM) CompareExchangeAdvancedStr 

func (self *RemoteDBM) CompareExchangeAdvancedStr(
    key interface{}, expected interface{}, desired interface{},
    retryWait float64, notify bool) (string, *Status)

Does compare-and-exchange and/or gets the old value of the record, as a string.

@param key The key of the record.
@param expected The expected value. If it is nil or NilString, no existing record is expected. If it is AnyBytes or AnyString, an existing record with any value is expacted.
@param desired The desired value. If it is nil or NilString, the record is to be removed. If it is AnyBytes or AnyString, no update is done.
@param retryWait 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.
@param notify If true, a notification signal is sent to wake up retrying threads.
@return The old value and the result status. If the condition doesn't meet, the state is INFEASIBLE_ERROR. If there's no existing record, the value is NilString.

func (*RemoteDBM) CompareExchangeMulti 

func (self *RemoteDBM) CompareExchangeMulti(
    expected []KeyValuePair, desired []KeyValuePair) *Status

Compares the values of records and exchanges if the condition meets.

@param expected A sequence of pairs of the record keys and their expected values. If the value is nil, no existing record is expected. If the value is AnyBytes, an existing record with any value is expacted.
@param desired A sequence of pairs of the record keys and their desired values. If the value is nil, the record is to be removed.
@return The result status. If the condition doesn't meet, StatusInfeasibleError is returned.

func (*RemoteDBM) CompareExchangeMultiStr 

func (self *RemoteDBM) CompareExchangeMultiStr(
    expected []KeyValueStrPair, desired []KeyValueStrPair) *Status

Compares the values of records and exchanges if the condition meets, using string data.

@param expected A sequence of pairs of the record keys and their expected values. If the value is NilString, no existing record is expected. If the value is AnyString, an existing record with any value is expacted.
@param desired A sequence of pairs of the record keys and their desired values. If the value is NilString, the record is to be removed.
@return The result status. If the condition doesn't meet, StatusInfeasibleError is returned.

func (*RemoteDBM) Connect 

func (self *RemoteDBM) Connect(address string, timeout float64, auth_config string) *Status

Connects to the server.

@param 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".
@param timeout The timeout in seconds for connection and each operation. Negative means unlimited.
@param 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.
@return The result status.

func (*RemoteDBM) Count 

func (self *RemoteDBM) Count() (int64, *Status)

Gets the number of records.

@return The number of records and the result status.

func (*RemoteDBM) CountSimple 

func (self *RemoteDBM) CountSimple() int64

Gets the number of records, in a simple way.

@return The number of records or -1 on failure.

func (*RemoteDBM) Disconnect 

func (self *RemoteDBM) Disconnect() *Status

Disconnects the connection to the server.

@return The result status.

func (*RemoteDBM) Each 

func (self *RemoteDBM) Each() <-chan KeyValuePair

Makes a channel to read each records.

@return the channel to read each records. All values should be read from the channel to avoid resource leak.

func (*RemoteDBM) EachStr 

func (self *RemoteDBM) EachStr() <-chan KeyValueStrPair

Makes a channel to read each records, as strings.

@return the channel to read each records. All values should be read from the channel to avoid resource leak.

func (*RemoteDBM) Echo 

func (self *RemoteDBM) Echo(message string) (string, *Status)

Sends a message and gets back the echo message.

@param message The message to send.
@param status A status object to which the result status is assigned. It can be omitted.
@return The string value of the echoed message or None on failure.

func (*RemoteDBM) Get 

func (self *RemoteDBM) Get(key interface{}) ([]byte, *Status)

Gets the value of a record of a key.

@param key The key of the record.
@return The bytes value of the matching record and the result status. If there's no matching record, the status is StatusNotFoundError.

func (*RemoteDBM) GetFileSize 

func (self *RemoteDBM) GetFileSize() (int64, *Status)

Gets the current file size of the database.

@return The current file size of the database and the result status.

func (*RemoteDBM) GetFileSizeSimple 

func (self *RemoteDBM) GetFileSizeSimple() int64

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

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

func (*RemoteDBM) GetMulti 

func (self *RemoteDBM) GetMulti(keys []string) map[string][]byte

Gets the values of multiple records of keys.

@param keys The keys of records to retrieve.
@return A map of retrieved records. Keys which don't match existing records are ignored.

func (*RemoteDBM) GetMultiStr 

func (self *RemoteDBM) GetMultiStr(keys []string) map[string]string

Gets the values of multiple records of keys, as strings.

@param keys The keys of records to retrieve.
@eturn A map of retrieved records. Keys which don't match existing records are ignored.

func (*RemoteDBM) GetSimple 

func (self *RemoteDBM) GetSimple(key interface{}, defaultValue interface{}) []byte

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

@param key The key of the record.
@param defaultValue The value to be returned on failure.
@return The value of the matching record on success, or the default value on failure.

func (*RemoteDBM) GetStr 

func (self *RemoteDBM) GetStr(key interface{}) (string, *Status)

Gets the value of a record of a key, as a string.

@param key The key of the record.
@return The string value of the matching record and the result status. If there's no matching record, the status is StatusNotFoundError.

func (*RemoteDBM) GetStrSimple 

func (self *RemoteDBM) GetStrSimple(key interface{}, defaultValue interface{}) string

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

@param key The key of the record.
@param defaultValue The value to be returned on failure.
@return The value of the matching record on success, or the default value on failure.

func (*RemoteDBM) Increment 

func (self *RemoteDBM) Increment(
    key interface{}, inc interface{}, init interface{}) (int64, *Status)

Increments the numeric value of a record.

@param key The key of the record.
@param inc The incremental value. If it is Int64Min, the current value is not changed and a new record is not created.
@param init The initial value.
@return The current value and the result status.

func (*RemoteDBM) Inspect 

func (self *RemoteDBM) Inspect() map[string]string

Inspects the database.

@return A map of property names and their values.

If the DBM index is negative, basic metadata of all DBMs are obtained.

func (*RemoteDBM) MakeIterator 

func (self *RemoteDBM) MakeIterator() *Iterator

Makes an iterator for each record.

@return The iterator for each record.

Every iterator should be destructed explicitly by the "Destruct" method.

func (*RemoteDBM) PopFirst 

func (self *RemoteDBM) PopFirst(retryWait float64) ([]byte, []byte, *Status)

Gets the first record and removes it.

@param retryWait 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.
@return The key and the value of the first record, and the result status.

func (*RemoteDBM) PopFirstStr 

func (self *RemoteDBM) PopFirstStr(retryWait float64) (string, string, *Status)

Gets the first record as strings and removes it.

@param retryWait 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.
@return The key and the value of the first record, and the result status.

func (*RemoteDBM) PushLast 

func (self *RemoteDBM) PushLast(value interface{}, wtime float64, notify bool) *Status

Adds a record with a key of the current timestamp.

@param value The value of the record.
@param wtime The current wall time used to generate the key. If it is None, the system clock is used.
@param notify If true, notification signal is sent.
@return The result status.

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.

func (*RemoteDBM) Rebuild 

func (self *RemoteDBM) Rebuild(params map[string]string) *Status

Rebuilds the entire database.

@param params Optional parameters. If it is nil, it is ignored.
@return The result status.

The optional parameters are the same as the Open method of the local DBM class and the database configurations of the server command. Omitted tuning parameters are kept the same or implicitly optimized.

In addition, HashDBM, TreeDBM, and SkipDBM supports the following parameters.

skip_broken_records (bool): If true, the operation continues even if there are broken records which can be skipped.
sync_hard (bool): If true, physical synchronization with the hardware is done before finishing the rebuilt file.

func (*RemoteDBM) Rekey 

func (self *RemoteDBM) Rekey(oldKey interface{}, newKey interface{},
    overwrite bool, copying bool) *Status

Changes the key of a record.

@param oldKey The old key of the record.
@param newKey The new key of the record.
@param overwrite Whether to overwrite the existing record of the new key.
@param copying Whether to retain the record of the old key.
@return The result status. If there's no matching record to the old key, NOT_FOUND_ERROR is returned. If the overwrite flag is false and there is an existing record of the new key, DUPLICATION ERROR is returned.

This method is done atomically by ProcessMulti. The other threads observe that the record has either the old key or the new key. No intermediate states are observed.

func (*RemoteDBM) Remove 

func (self *RemoteDBM) Remove(key interface{}) *Status

Removes a record of a key.

@param key The key of the record.
@return The result status. If there's no matching record, StatusNotFoundError is returned.

func (*RemoteDBM) RemoveMulti 

func (self *RemoteDBM) RemoveMulti(keys []string) *Status

Removes records of keys.

@param key The keys of the records.
@return The result status. If there are missing records, StatusNotFoundError is returned.

func (*RemoteDBM) Search 

func (self *RemoteDBM) Search(mode string, pattern string, capacity int) []string

Searches the database and get keys which match a pattern.

@param 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.
@param pattern The pattern for matching.
@param capacity The maximum records to obtain. 0 means unlimited.
@return A list of keys matching the condition.

func (*RemoteDBM) Set 

func (self *RemoteDBM) Set(key interface{}, value interface{}, overwrite bool) *Status

Sets a record of a key and a value.

@param key The key of the record.
@param value The value of the record.
@param overwrite Whether to overwrite the existing value.
@return The result status. If overwriting is abandoned, StatusDuplicationError is returned.

func (*RemoteDBM) SetDBMIndex 

func (self *RemoteDBM) SetDBMIndex(dbmIndex int32) *Status

Sets the index of the DBM to access.

@param dbmIndex The index of the DBM to access.
@eturn The result status.

func (*RemoteDBM) SetMulti 

func (self *RemoteDBM) SetMulti(records map[string][]byte, overwrite bool) *Status

Sets multiple records.

@param records Records to store.
@param 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.
@return The result status. If there are records avoiding overwriting, StatusDuplicationError is returned.

func (*RemoteDBM) SetMultiStr 

func (self *RemoteDBM) SetMultiStr(records map[string]string, overwrite bool) *Status

Sets multiple records, with string data.

@param records Records to store.
@param 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.
@return The result status. If there are records avoiding overwriting, StatusDuplicationError is set.

func (*RemoteDBM) ShouldBeRebuilt 

func (self *RemoteDBM) ShouldBeRebuilt() (bool, *Status)

Checks whether the database should be rebuilt.

@return The result decision and the result status. The decision is true to be optimized or false with no necessity.

func (*RemoteDBM) ShouldBeRebuiltSimple 

func (self *RemoteDBM) ShouldBeRebuiltSimple() bool

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

@return True to be optimized or false with no necessity.

func (*RemoteDBM) String 

func (self *RemoteDBM) String() string

Makes a string representing the remote database.

@return The string representing the remote database.

func (*RemoteDBM) Synchronize 

func (self *RemoteDBM) Synchronize(hard bool, params map[string]string) *Status

Synchronizes the content of the database to the file system.

@param hard True to do physical synchronization with the hardware or false to do only logical synchronization with the file system.
@param params Optional parameters. If it is nil, it is ignored.
@return The result status.

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.

type Status

Status of operations. 

type Status struct {
    // contains filtered or unexported fields
}

func NewStatus 

func NewStatus(args ...interface{}) *Status

Makes a new status, with variable length arguments.

@param args If the first parameter is given, it is treated as the status code. If the second parameter is given, it is treated as the status message.
@return The pointer to the created status object.

func NewStatus1 

func NewStatus1(code StatusCode) *Status

Makes a new status, with a code.

@param code The status code.
@return The pointer to the created status object.

func NewStatus2 

func NewStatus2(code StatusCode, message string) *Status

Makes a new status, with a code and a message.

@param code The status code.
@param code The status message.
@return The pointer to the created status object.

func (*Status) Equals 

func (self *Status) Equals(rhs interface{}) bool

Checks whether the status equal to another status.

@param rhs a status object or a status code.
@param true for the both operands are equal, or false if not.

func (*Status) Error 

func (self *Status) Error() string

Makes a string representing the status, to be an error.

@return The string representing the code. As the string contains only the code, comparison
of the result strings is not affected by difference of the status messages. the additiona

func (*Status) GetCode 

func (self *Status) GetCode() StatusCode

Gets the status code.

@return The status code.

func (*Status) GetMessage 

func (self *Status) GetMessage() string

Gets the status message.

@return The status message.

func (*Status) IsOK 

func (self *Status) IsOK() bool

Returns true if the status is success.

@return true if the status is success, or false if not.

func (*Status) Join 

func (self *Status) Join(rhs *Status)

Assigns the internal state from another status object only if the current state is success.

@param rhs The status object.

func (*Status) OrDie 

func (self *Status) OrDie()

Causes a panic if the status is not success.

func (*Status) Set 

func (self *Status) Set(args ...interface{})

Sets the code and the message.

@param code The status code.
@param message An arbitrary status message. If it is omitted, no message is set.

func (*Status) String 

func (self *Status) String() string

Makes a string representing the status.

@return The string representing the status.

type StatusCode

Type alias for the enumeration of status codes. 

type StatusCode int32