func IsDelError(err error) bool
IsDelError returns true if the given error is or contains DiveDeleteError error.
func IsDuplicateStorageError(err error) bool
IsDuplicateStorageError returns true if the given error is or contains DiveDuplicateStorageError error.
func IsGetError(err error) bool
IsGetError returns true if the given error is or contains DiveGetError error.
func IsIncrError(err error) bool
IsIncrError returns true if the given error is or contains DiveIncrError error.
func IsInvalidKeyError(err error) bool
IsInvalidKeyError returns true if the given error is or contains DiveInvalidKeyError error.
func IsInvalidRangeParametersError(err error) bool
IsInvalidRangeParametersError returns true if the given error is or contains DiveInvalidRangeParametersError error.
func IsInvalidStorageNameError(err error) bool
IsInvalidStorageNameError returns true if the given error is or contains DiveInvalidStorageNameError error.
func IsInvalidTTLError(err error) bool
IsInvalidTTLError returns true if the given error is or contains DiveInvalidTTLError error.
func IsInvalidValueTypeError(err error) bool
IsInvalidValueTypeError returns true if the given error is or contains DiveInvalidValueTypeError error.
func IsKeyExpiredError(err error) bool
IsKeyExpiredError returns true if the given error is or contains DiveKeyExpiredError error.
func IsNewStorageError(err error) bool
IsNewStorageError returns true if the given error is or contains DiveNewStorageError error.
func IsNodeAddressNotFoundError(err error) bool
IsNodeAddressNotFoundError returns true if the given error is or contains DiveNodeAddressNotFoundError error.
func IsNodeNotFoundError(err error) bool
IsNodeNotFoundError returns true if the given error is or contains DiveNodeNotFoundError error.
func IsPopError(err error) bool
IsPopError returns true if the given error is or contains DivePopError error.
func IsPushError(err error) bool
IsPushError returns true if the given error is or contains DivePushError error.
func IsRangeError(err error) bool
IsRangeError returns true if the given error is or contains DiveRangeError error.
func IsReadyToShutdown() bool
IsReadyToShutdown returns true when Dive module is ready to shutdown.
[NOTE] This function is used internally.
func IsSetError(err error) bool
IsSetError returns true if the given error is or contains DiveSetError error.
func IsSetIfNotExistError(err error) bool
IsSetIfNotExistError returns true if the given error is or contains DiveSetIfNotExistError error.
func IsSetupError(err error) bool
IsSetupError returns true if the given error is or contains DiveSetupError error.
func SetOnLRangeByStorageName(name string, cb func(list [][]byte) [][]byte) bool
SetOnLRangeByStorageName assigns a callback to be invoked on every LRange call by storage name.
[IMPORTANT] This callback must be assigned on the target node server.
Default target node server is HTTP, but it can be configured to something else.
[IMPORTANT] This function is not goroutine safe. It means that it should be used only during the setup of the server.
[IMPORTANT] The callback receives an array of interface{} NOT *Result.
In order to handle each interface{} element, you must use util module's To...() function.
Example:
assigned := SetOnLRangeByStorageName(storageName, func(list []interface{}) []interface{} {
for i := 0; i < len(list); i++ {
value, ok := util.ToFloat32(list[i])
}
})
Parameters
name - Storage name to assign the callback.
cb - Callback function to be executed on every LRange.
The callback will be passed the entire list data and the returned list data will be the returned value of LRange.
func SetOnPushByStorageName(name string, cb func(key string, list [][]byte) [][]byte) bool
SetOnPushByStorageName assigns a callback to be invoked on every LPush and RPush for the specified storage by its name.
[IMPORTANT] This callback must be assigned on the target node server.
Default target node server is HTTP, but it can be configured to something else.
[IMPORTANT] This function is not goroutine safe. It means that it should be used only during the setup of the server.
[IMPORTANT] The callback is invoked while the mutex lock is held. You must avoid using mutex lock in the callback to avoid mutex deadlock.
[IMPORTANT] The callback receives an array of interface{} NOT *Result.
In order to handle each interface{} element, you must use util module's To...() function.
Example:
assigned := SetOnPushByStorageName(storageName, func(list []interface{}) []interface{} {
for i := 0; i < len(list); i++ {
value, ok := util.ToFloat32(list[i])
}
})
Parameters
name - Storage name to assign the callback.
cb - Callback function to be executed on every LPush and RPush.
The callback will be passed the entire list data and the returned list data will be stored on the storage.
func SetOnReady(cb func())
SetOnReady assigns a callback to be invoked when Dive module is ready.
func Setup(confpath string)
Setup must be invoked before calling diarkis.Start() in order to use dive module.
[IMPORTANT] Setup operation is asynchronous and Dive will not be ready immediately.
You must wait for diarkis.OnReady callbacks to ensure the readiness of Dive module.
Options represents optional configurations for New(name string, options *Options) to create a new storage without the use of configuration file.
type Options struct {
MultipleIndex uint8
RingSize uint32
TargetNodeType string
Migration bool
MigrationBatchSize uint16
MigrationInterval uint16
}
Result represents the returned value of the function that returns a value or values. This struct is meant to type cast the returned result value.
type Result struct {
// contains filtered or unexported fields
}
func (r *Result) IsError() bool
IsError returns true if the result is an error.
You may retrieve the error by calling ToError().
func (r *Result) ToBool() (bool, error)
ToBool returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToBoolArray() ([]bool, error)
ToBoolArray returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToBytes() ([]byte, error)
ToBytes returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
When you use raw []byte as the value, you may consider to use something like td package of Diarkis.
td package comes with a data struct called td.TransportData that allows you to pre-define data structure and convert to []byte and back.
Define Data Structure
sampleData := td.DefineTransportData([]td.Property{
td.Property{ Name: "SampleName", Type: td.Int32 },
td.Property{ Name: "SampleNameList", Type: td.StringArray },
})
Use defined td.TransportData
sd := sampleData.New()
sd.SetAsInt32("SampleName", 1024)
sd.SetAsStringArray("SampleNameList", []string{
"Cat",
"Dog",
"Lizard",
"Bird",
})
// Convert it to []byte
packed := sd.Pack()
// Convert packed []byte to sampleData
sd2 := sampleData.New()
sd2.Unpack(packed)
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToBytesArray() ([][]byte, error)
ToBytesArray returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToError() error
ToError returns an error if the result is an error.
If the result is not an error, it will return nil.
To check if the result is an error or not, use IsError().
func (r *Result) ToFloat32() (float32, error)
ToFloat32 returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToFloat32Array() ([]float32, error)
ToFloat32Array returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToFloat64() (float64, error)
ToFloat64 returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToFloat64Array() ([]float64, error)
ToFloat64Array returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToInt16() (int16, error)
ToInt16 returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToInt16Array() ([]int16, error)
ToInt16Array returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToInt32() (int32, error)
ToInt32 returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToInt32Array() ([]int32, error)
ToInt32Array returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToInt64() (int64, error)
ToInt64 returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToInt64Array() ([]int64, error)
ToInt64Array returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToInt8() (int8, error)
ToInt8 returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToInt8Array() ([]int8, error)
ToInt8Array returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToString() (string, error)
ToString returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToStringArray() ([]string, error)
ToStringArray returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToUint16() (uint16, error)
ToUint16 returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
func (r *Result) ToUint16Array() ([]uint16, error)
ToUint16Array returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToUint32() (uint32, error)
ToUint32 returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToUint32Array() ([]uint32, error)
ToUint32Array returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToUint64() (uint64, error)
ToUint64 returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToUint64Array() ([]uint64, error)
ToUint64Array returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToUint8() (uint8, error)
ToUint8 returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
func (r *Result) ToUint8Array() ([]uint8, error)
ToUint8Array returns the result value of the function that returns a value or values as the specified data type.
[NOTE] If the function that returns *Result had an error, the second value gives an error. [NOTE] If the returned result value is not the specific data type, the second returned value gives an error.
If the value data type is not what is asked for, it will error out.
dive.IsInvalidValueTypeError(err error)
Storage represents the distributed data storage within Diarkis cluster.
type Storage struct {
// contains filtered or unexported fields
}
func GetStorageByName(name string) *Storage
GetStorageByName returns a storage by the given name.
You must use this function to get a storage if you define storage names in the configuration JSON.
The function returns nil if the given name does not match existing storages.
func New(name string, options *Options) (*Storage, error)
New creates an instance of Storage struct to interact with the distributed storage if the key does not exist.
If you define storage names in the configuration JSON file, you do not need to use this function. Use GetStorageByName(name string) instead.
Error Cases
┌────────────────────────┬──────────────────────────────────────────────────────────────┐ │ Error │ Reason │ ╞════════════════════════╪══════════════════════════════════════════════════════════════╡ │ Setup must be invoked │ In order to use Dive module, │ │ │ dive.Setup() must be called before calling diarkis.Start() │ ├────────────────────────┼──────────────────────────────────────────────────────────────┤ │ Name must not be empty │ Input given name is an empty string. │ ├────────────────────────┼──────────────────────────────────────────────────────────────┤ │ Storage already exists │ The given storage name already exists. │ └────────────────────────┴──────────────────────────────────────────────────────────────┘
Parameters
name - Unique name for the storage. options - Optional configurations for the new storage.
func (s *Storage) Del(key string) *Result
Del deletes the key and value pair after retrieves the value of the given key.
[IMPORTANT] The function uses mutex lock internally. [IMPORTANT] The function is asynchronous internally and accesses a remote node in the Diarkis cluster. [IMPORTANT] The function may fail during key migration.
The returned value is the value of the given key that has been deleted.
Error Cases
┌────────────────────────────────┬─────────────────────────────────────────────────────────────────────────┐ │ Error │ Reason │ ╞════════════════════════════════╪═════════════════════════════════════════════════════════════════════════╡ │ Setup must be invoked │ In order to use Dive module, │ │ │ dive.Setup() must be called before calling diarkis.Start() │ ├────────────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ Key must not be empty │ Input given key is an empty string. │ ├────────────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ Storage node address not found │ There is no node that stores the given key. │ ├────────────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ Storage does not exist │ The storage cannot be found on the designated node. │ ├────────────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ Key does not exists │ The given key does not exist in the storage. │ ├────────────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ Network errors │ Internal network error such as reliable communication time out etc. │ └────────────────────────────────┴─────────────────────────────────────────────────────────────────────────┘
The possible error evaluations:
Besides the following errors, there are Mesh module errors as well.
dive.IsSetupError(err error) // Dive has not been setup dive.IsInvalidKeyError(err error) // Invalid or empty key provided dive.IsNodeNotFoundError(err error) // Dive storage server node not found dive.IsNodeAddressNotFoundError(err error) // Dive storage server node address not found by the given key dive.IsDelError(err error) // Dive Del failure
▶︎ Return Data
The function returns an instance of *Result. To retrieve the data according to the correct data type, *Result has To...() functions.
Example:
// If the intended result value is a string value, err := storage.Del(key).ToString() // If the intended result value is an array of float32 values, err := storage.Del(anotherKey).ToFloat32Array()
Parameters
key - The key of the value to retrieve and delete.
func (s *Storage) Get(key string) *Result
Get retrieves the value of the given key.
[IMPORTANT] The function uses mutex lock internally. [IMPORTANT] The function is asynchronous internally and accesses a remote node in the Diarkis cluster. [IMPORTANT] The function may fail during key migration.
Error Cases
┌────────────────────────────────┬───────────────────────────────────────────────────────────────────────┐ │ Error │ Reason │ ╞════════════════════════════════╪═══════════════════════════════════════════════════════════════════════╡ │ Setup must be invoked │ In order to use Dive module, │ │ │ dive.Setup() must be called before calling diarkis.Start() │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key must not be empty │ Input given key is an empty string. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage node address not found │ There is no node that stores the given key. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage does not exist │ The storage cannot be found on the designated node. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key has expired │ The given key has expired, but not yet deleted from the memory. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key does not exists │ The given key does not exist in the storage. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Network errors │ Internal network error such as reliable communication time out etc. │ └────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
The possible error evaluations:
Besides the following errors, there are Mesh module errors as well.
dive.IsSetupError(err error) // Dive has not been setup dive.IsInvalidKeyError(err error) // Invalid or empty key provided dive.IsNodeNotFoundError(err error) // Dive storage server node not found dive.IsNodeAddressNotFoundError(err error) // Dive storage server node address not found by the given key dive.IsGetError(err error) // Dive Get failure
▶︎ Return Data
The function returns an instance of *Result. To retrieve the data according to the correct data type, *Result has To...() functions.
Example:
// If the intended result value is a string value, err := storage.Get(key).ToString() // If the intended result value is an array of float32 values, err := storage.Get(anotherKey).ToFloat32Array()
Parameters
key - The key of the value to retrieve.
func (s *Storage) GetEx(key string, ttl uint32) *Result
GetEx retrieves the value of the given key.
[IMPORTANT] The function uses mutex lock internally. [IMPORTANT] The function is asynchronous internally and accesses a remote node in the Diarkis cluster. [IMPORTANT] The function may fail during key migration.
Error Cases
┌────────────────────────────────┬───────────────────────────────────────────────────────────────────────┐ │ Error │ Reason │ ╞════════════════════════════════╪═══════════════════════════════════════════════════════════════════════╡ │ Setup must be invoked │ In order to use Dive module, │ │ │ dive.Setup() must be called before calling diarkis.Start() │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key must not be empty │ Input given key is an empty string. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage node address not found │ There is no node that stores the given key. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage does not exist │ The storage cannot be found on the designated node. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ TTL exceeds 86400 ms │ TTL must not exceed 86400 ms (24 hours). │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key has expired │ The given key has expired, but not yet deleted from the memory. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key does not exists │ The given key does not exist in the storage. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Network errors │ Internal network error such as reliable communication time out etc. │ └────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
The possible error evaluations:
Besides the following errors, there are Mesh module errors as well.
dive.IsSetupError(err error) // Dive has not been setup dive.IsInvalidStorageNameError(err error) // Invalid storage name dive.IsInvalidKeyError(err error) // Invalid or empty key provided dive.IsNodeNotFoundError(err error) // Dive storage server node not found dive.IsNodeAddressNotFoundError(err error) // Dive storage server node address not found by the given key dive.IsInvalidTTLError(err error) // Provided TTL is invalid dive.IsGetError(err error) // Dive Get failure
▶︎ Return Data
The function returns an instance of *Result. To retrieve the data according to the correct data type, *Result has To...() functions.
Example:
// If the intended result value is a string value, err := storage.GetEx(key, ttl).ToString() // If the intended result value is an array of float32 values, err := storage.GetEx(anotherKey, ttl).ToFloat32Array()
Parameters
key - The key of the value to retrieve.
ttl - If greater than 0 is given, TTL of the key will be extended.
TTL must not exceed 86400. TTL is in seconds.
func (s *Storage) GetLocalKeys() []string
GetLocalKeys returns an array of locally stored keys.
func (s *Storage) GetNumberOfNodes() int
GetNumberOfNodes returns the number of recognized nodes for Dive.
func (s *Storage) IncrBy(key string, increment int32) *Result
IncrBy increments the stored value by the given increment amount.
[IMPORTANT] The function uses mutex lock internally.
[IMPORTANT] Value to increment must be of the data type int32
[IMPORTANT] The function is asynchronous internally and accesses a remote node in the Diarkis cluster.
[IMPORTANT] The key and value pair WILL expire in 24 hours.
Default TTL can be configured to be other than 24 hours.
Error Cases
┌────────────────────────────────┬───────────────────────────────────────────────────────────────────────┐ │ Error │ Reason │ ╞════════════════════════════════╪═══════════════════════════════════════════════════════════════════════╡ │ Setup must be invoked │ In order to use Dive module, │ │ │ dive.Setup() must be called before calling diarkis.Start() │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key must not be empty │ Input given key is an empty string. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage node address not found │ There is no node that stores the given key. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage does not exist │ The storage cannot be found on the designated node. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key does not exist │ The key and its value must exist. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Invalid data type to increment │ The value must be int32. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Network errors │ Internal network error such as reliable communication time out etc. │ └────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
Parameters
key - The key of the given value to be stored. increment - The increment amount of the value stored.
The possible error evaluations:
Besides the following errors, there are Mesh module errors as well.
dive.IsSetupError(err error) // Dive has not been setup dive.IsInvalidStorageNameError(err error) // Invalid storage name dive.IsInvalidKeyError(err error) // Invalid or empty key provided dive.IsNodeNotFoundError(err error) // Dive storage server node not found dive.IsNodeAddressNotFoundError(err error) // Dive storage server node address not found by the given key dive.IsIncrError(err error) // Dive IncrBy failure
func (s *Storage) IncrByEx(key string, increment int32, ttl int64) *Result
IncrByEx increments the stored value by the given increment amount.
[IMPORTANT] The function uses mutex lock internally.
[IMPORTANT] Value to increment must be of the data type int32
[IMPORTANT] The function is asynchronous internally and accesses a remote node in the Diarkis cluster.
[IMPORTANT] The key and value pair WILL expire in 24 hours.
Default TTL can be configured to be other than 24 hours.
Error Cases
┌────────────────────────────────┬───────────────────────────────────────────────────────────────────────┐ │ Error │ Reason │ ╞════════════════════════════════╪═══════════════════════════════════════════════════════════════════════╡ │ Setup must be invoked │ In order to use Dive module, │ │ │ dive.Setup() must be called before calling diarkis.Start() │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key must not be empty │ Input given key is an empty string. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage node address not found │ There is no node that stores the given key. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage does not exist │ The storage cannot be found on the designated node. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key does not exist │ The key and its value must exist. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Invalid data type to increment │ The value must be int32. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Network errors │ Internal network error such as reliable communication time out etc. │ └────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
Parameters
key - The key of the given value to be stored.
increment - The increment amount of the value stored.
ttl - If greater than 0 is given, TTL of the key will be extended.
TTL must not exceed 86400. TTL is in seconds.
The possible error evaluations:
Besides the following errors, there are Mesh module errors as well.
dive.IsSetupError(err error) // Dive has not been setup dive.IsInvalidStorageNameError(err error) // Invalid storage name dive.IsInvalidKeyError(err error) // Invalid or empty key provided dive.IsNodeNotFoundError(err error) // Dive storage server node not found dive.IsNodeAddressNotFoundError(err error) // Dive storage server node address not found by the given key dive.IsIncrError(err error) // Dive IncrBy failure
func (s *Storage) IsStorage() bool
IsStorage returns true, if the server node type is the configured target node type.
[NOTE] Default target node type is HTTP.
func (s *Storage) LPop(key string, howmany int) (*Result, error)
LPop returns an array of elements from the list set created by LPush and/or RPush from index 0 up to the number given by howmany parameter.
The returned elements will be atomically removed from the list set.
[IMPORTANT] The function uses mutex lock internally. [IMPORTANT] The function is asynchronous internally and accesses a remote node in the Diarkis cluster. [IMPORTANT] The function may fail during key migration.
Error Cases
┌────────────────────────────────┬───────────────────────────────────────────────────────────────────────┐ │ Error │ Reason │ ╞════════════════════════════════╪═══════════════════════════════════════════════════════════════════════╡ │ Setup must be invoked │ In order to use Dive module, │ │ │ dive.Setup() must be called before calling diarkis.Start() │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key must not be empty │ Input given key is an empty string. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage node address not found │ There is no node that stores the given key. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage does not exist │ The storage cannot be found on the designated node. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key has expired │ The given key has expired, but not yet deleted from the memory. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key does not exists │ The given key does not exist in the storage. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Network errors │ Internal network error such as reliable communication time out etc. │ └────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
The possible error evaluations:
Besides the following errors, there are Mesh module errors as well.
dive.IsSetupError(err error) // Dive has not been setup dive.IsInvalidStorageNameError(err error) // Invalid storage name dive.IsInvalidKeyError(err error) // Invalid or empty key provided dive.IsNodeNotFoundError(err error) // Dive storage server node not found dive.IsNodeAddressNotFoundError(err error) // Dive storage server node address not found by the given key dive.IsPopError(err error) // Dive Pop failure
▶︎ Return Data
The function returns an instance of *Result. To retrieve the data according to the correct data type, *Result has To...() functions.
Example:
// If the intended result value is an array of strings
result, err := storage.LPop(key, 10)
if err != nil {
// handle error...
}
int64List, err := result.ToInt64Array()
if err != nil {
// the value is not int64 array...
}
Parameters
key - The key of the value to retrieve.
howmany - Number of elements from the list set to pop.
If the number is greater than the length of the list set, it will pop all elements.
If 0 or below given, the entire list will be popped.
func (s *Storage) LPopEx(key string, howmany int, ttl uint32) (*Result, error)
LPopEx returns an array of elements from the list set created by LPush and/or RPush from index 0 up to the number given by howmany parameter.
The returned elements will be atomically removed from the list set.
[IMPORTANT] The function uses mutex lock internally. [IMPORTANT] The function is asynchronous internally and accesses a remote node in the Diarkis cluster. [IMPORTANT] The function may fail during key migration.
Error Cases
┌────────────────────────────────┬───────────────────────────────────────────────────────────────────────┐ │ Error │ Reason │ ╞════════════════════════════════╪═══════════════════════════════════════════════════════════════════════╡ │ Setup must be invoked │ In order to use Dive module, │ │ │ dive.Setup() must be called before calling diarkis.Start() │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key must not be empty │ Input given key is an empty string. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage node address not found │ There is no node that stores the given key. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage does not exist │ The storage cannot be found on the designated node. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key has expired │ The given key has expired, but not yet deleted from the memory. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key does not exists │ The given key does not exist in the storage. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ TTL exceeds 86400 s │ TTL must not exceed 86400 s (24 hours). │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Network errors │ Internal network error such as reliable communication time out etc. │ └────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
The possible error evaluations:
Besides the following errors, there are Mesh module errors as well.
dive.IsSetupError(err error) // Dive has not been setup dive.IsInvalidStorageNameError(err error) // Invalid storage name dive.IsInvalidKeyError(err error) // Invalid or empty key provided dive.IsNodeNotFoundError(err error) // Dive storage server node not found dive.IsNodeAddressNotFoundError(err error) // Dive storage server node address not found by the given key dive.IsInvalidTTLError(err error) // Provided TTL is invalid dive.IsPopError(err error) // Dive Pop failure
▶︎ Return Data
The function returns an instance of *Result. To retrieve the data according to the correct data type, *Result has To...() functions.
Example:
// If the intended result value is an array of strings
result, err := storage.LPopEx(key, 10, ttl)
if err != nil {
// handle error...
}
int64List, err := result.ToInt64Array()
if err != nil {
// the value is not int64 array...
}
Parameters
key - The key of the value to retrieve.
howmany - Number of elements from the list set to pop.
If the number is greater than the length of the list set, it will pop all elements.
If 0 or below given, the entire list will be popped.
ttl - If greater than 0, TTL of the key will be extended.
TTL must not exceed 86400. TTL is in seconds.
func (s *Storage) LPush(key string, values ...[]byte) error
LPush stores a value as an element of a list associated to the given key on a node derived from the given key and assigns a TTL for the key and value to expire.
The value as an element is pushed to the front of the array and it updates internal timestamp and TTL.
[CRITICALLY IMPORTANT] The value must NOT be struct or contain struct.
[IMPORTANT] The function uses mutex lock internally.
[IMPORTANT] Value data type must be either primitive, string, or []byte.
[IMPORTANT] The function is asynchronous internally and accesses a remote node in the Diarkis cluster.
[IMPORTANT] The key WILL expire in 24 hours.
Default TTL can be configured to be other than 24 hours.
[IMPORTANT] Every LPush updates TTL of the key.
Error Cases
┌────────────────────────────────┬───────────────────────────────────────────────────────────────────────┐ │ Error │ Reason │ ╞════════════════════════════════╪═══════════════════════════════════════════════════════════════════════╡ │ Setup must be invoked │ In order to use Dive module, │ │ │ dive.Setup() must be called before calling diarkis.Start() │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key must not be empty │ Input given key is an empty string. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage node address not found │ There is no node that stores the given key. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage does not exist │ The storage cannot be found on the designated node. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key already exists │ The given key already exists. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Network errors │ Internal network error such as reliable communication time out etc. │ └────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
The possible error evaluations:
Besides the following errors, there are Mesh module errors as well.
dive.IsSetupError(err error) // Dive has not been setup dive.IsInvalidStorageNameError(err error) // Invalid storage name dive.IsInvalidKeyError(err error) // Invalid or empty key provided dive.IsNodeNotFoundError(err error) // Dive storage server node not found dive.IsNodeAddressNotFoundError(err error) // Dive storage server node address not found by the given key dive.IsInvalidValueTypeError(err error) // Provided value type is invalid dive.IsPushError(err error) // Dive Push failure
Parameters
key - The key of the given value to be stored.
value - Value of the given key to be stored.
You may pass multiple values to push multiple elements to the list set.
Examples:
LPush(key, 1, 2, 3)
LPush(key, []interface{}{1, 2, 3}...)
func (s *Storage) LPushEx(key string, ttl uint32, values ...[]byte) error
LPushEx stores a value as an element of a list associated to the given key on a node derived from the given key and assigns a TTL for the key and value to expire.
The value as an element is pushed to the front of the array and it updates internal timestamp and TTL.
[CRITICALLY IMPORTANT] The value must NOT be struct or contain struct. [IMPORTANT] The function uses mutex lock internally. [IMPORTANT] Value data type must be either primitive, string, or []byte. [IMPORTANT] The function is asynchronous internally and accesses a remote node in the Diarkis cluster. [IMPORTANT] Every LPushEX updates TTL of the key.
Error Cases
┌────────────────────────────────┬───────────────────────────────────────────────────────────────────────┐ │ Error │ Reason │ ╞════════════════════════════════╪═══════════════════════════════════════════════════════════════════════╡ │ Setup must be invoked │ In order to use Dive module, │ │ │ dive.Setup() must be called before calling diarkis.Start() │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key must not be empty │ Input given key is an empty string. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ TTL must not be 0 │ TTL must be greater than 0 second. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage node address not found │ There is no node that stores the given key. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage does not exist │ The storage cannot be found on the designated node. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key already exists │ The given key already exists. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ TTL exceeds 86400 ms │ TTL must not exceed 86400 ms (24 hours). │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Network errors │ Internal network error such as reliable communication time out etc. │ └────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
The possible error evaluations:
Besides the following errors, there are Mesh module errors as well.
dive.IsSetupError(err error) // Dive has not been setup dive.IsInvalidKeyError(err error) // Invalid or empty key provided dive.IsInvalidStorageNameError(err error) // Invalid storage name dive.IsNodeNotFoundError(err error) // Dive storage server node not found dive.IsNodeAddressNotFoundError(err error) // Dive storage server node address not found by the given key dive.IsInvalidValueTypeError(err error) // Provided value type is invalid dive.IsInvalidTTLError(err error) // Provided TTL is invalid dive.IsPushError(err error) // Dive Push failure
Parameters
key - The key of the given value to be stored.
ttl - TTL in seconds for the key and value pair to expire.
If greater than 0 is given, TTL of the key will be extended.
TTL must not exceed 86400. TTL is in seconds.
value - Value of the given key to be stored.
You may pass multiple values to push multiple elements to the list set.
Examples:
LPushEx(key, 1, 2, 3)
LPushEx(key, []interface{}{1, 2, 3}...)
func (s *Storage) LRange(key string, from, to int) *Result
LRange retrieves the value of the given key as an array. LRange can only work with either LPush or RPush.
[IMPORTANT] The function uses mutex lock internally. [IMPORTANT] The function is asynchronous internally and accesses a remote node in the Diarkis cluster. [IMPORTANT] The function may fail during key migration. [IMPORTANT] If the total length of the value list is smaller than the given range, LRange will retrieve the entire value list.
Error Cases
┌────────────────────────────────┬───────────────────────────────────────────────────────────────────────┐ │ Error │ Reason │ ╞════════════════════════════════╪═══════════════════════════════════════════════════════════════════════╡ │ Setup must be invoked │ In order to use Dive module, │ │ │ dive.Setup() must be called before calling diarkis.Start() │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key must not be empty │ Input given key is an empty string. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage node address not found │ There is no node that stores the given key. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage does not exist │ The storage cannot be found on the designated node. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Invalid range │ Given range is invalid: "from" must be less than "to". │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Invalid value │ The value of the given key is not a list. │ │ │ It means that the value is not stored by either LPush or RPush. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key has expired │ The given key has expired, but not yet deleted from the memory. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key does not exists │ The given key does not exist in the storage. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Network errors │ Internal network error such as reliable communication time out etc. │ └────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
The possible error evaluations:
Besides the following errors, there are Mesh module errors as well.
dive.IsSetupError(err error) // Dive has not been setup dive.IsInvalidStorageNameError(err error) // Invalid storage name dive.IsInvalidKeyError(err error) // Invalid or empty key provided dive.IsNodeNotFoundError(err error) // Dive storage server node not found dive.IsNodeAddressNotFoundError(err error) // Dive storage server node address not found by the given key dive.IsInvalidRangeParametersError(err error) // Range from and to parameters are invalid dive.IsRangeError(err error) // Dive Range failure
▶︎ Return Data
The function returns an instance of *Result. To retrieve the data according to the correct data type, *Result has To...() functions.
Example:
// If the intended result value is an array of strings
result := storage.LRange(key, 0, 10)
stringList, err := result.ToStringArray()
if err != nil {
// the value is not a string array...
}
Parameters
key - The key of the value to retrieve.
from - The index offset to read from. Example: from=0 to=10 will retrieve list[0:10]
to - The index offset to read to. Example: from=5 to=15 will retrieve list[5:15]
If you give 0 or below, LRange will retrieve the entire length of the list value.
func (s *Storage) LRangeEx(key string, from, to int, ttl uint32) *Result
LRangeEx retrieves the value of the given key as an array. LRange can only work with either LPush or RPush.
[IMPORTANT] The function uses mutex lock internally. [IMPORTANT] The function is asynchronous internally and accesses a remote node in the Diarkis cluster. [IMPORTANT] The function may fail during key migration. [IMPORTANT] If the total length of the value list is smaller than the given range, LRange will retrieve the entire value list.
Error Cases
┌────────────────────────────────┬───────────────────────────────────────────────────────────────────────┐ │ Error │ Reason │ ╞════════════════════════════════╪═══════════════════════════════════════════════════════════════════════╡ │ Setup must be invoked │ In order to use Dive module, │ │ │ dive.Setup() must be called before calling diarkis.Start() │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key must not be empty │ Input given key is an empty string. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage node address not found │ There is no node that stores the given key. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage does not exist │ The storage cannot be found on the designated node. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Invalid range │ Given range is invalid: "from" must be less than "to". │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Invalid value │ The value of the given key is not a list. │ │ │ It means that the value is not stored by either LPush or RPUsh. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key has expired │ The given key has expired, but not yet deleted from the memory. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key does not exists │ The given key does not exist in the storage. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ TTL exceeds 86400 ms │ TTL must not exceed 86400 ms (24 hours). │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Network errors │ Internal network error such as reliable communication time out etc. │ └────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
The possible error evaluations:
Besides the following errors, there are Mesh module errors as well.
dive.IsSetupError(err error) // Dive has not been setup dive.IsInvalidStorageNameError(err error) // Invalid storage name dive.IsInvalidKeyError(err error) // Invalid or empty key provided dive.IsNodeNotFoundError(err error) // Dive storage server node not found dive.IsNodeAddressNotFoundError(err error) // Dive storage server node address not found by the given key dive.IsInvalidRangeParametersError(err error) // Range from and to parameters are invalid dive.IsInvalidTTLError(err error) // Provided TTL is invalid dive.IsRangeError(err error) // Dive Range failure
▶︎ Return Data
The function returns an instance of *Result. To retrieve the data according to the correct data type, *Result has To...() functions.
Example:
// If the intended result value is an array of strings
results := storage.LRangeEx(key, 0, 10, ttl)
stringList, err := result.ToStringArray()
if err != nil {
// the value is not a string array...
}
Parameters
key - The key of the value to retrieve.
from - The index offset to read from. Example: from=0 to=10 will retrieve list[0:10]
to - The index offset to read to. Example: from=5 to=15 will retrieve list[5:15]
If you give 0 or below, LRange will retrieve the entire length of the list value.
ttl - If greater than 0 is given, TTL of the key will be extended.
TTL must not exceed 86400. TTL is in seconds.
func (s *Storage) RPop(key string, howmany int) (*Result, error)
RPop returns an array of elements from the list set created by LPush and/or RPush from the last element up to the number given by howmany in reverse order.
The returned elements will be atomically removed from the list set.
[IMPORTANT] The function uses mutex lock internally. [IMPORTANT] The function is asynchronous internally and accesses a remote node in the Diarkis cluster. [IMPORTANT] The function may fail during key migration.
Error Cases
┌────────────────────────────────┬───────────────────────────────────────────────────────────────────────┐ │ Error │ Reason │ ╞════════════════════════════════╪═══════════════════════════════════════════════════════════════════════╡ │ Setup must be invoked │ In order to use Dive module, │ │ │ dive.Setup() must be called before calling diarkis.Start() │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key must not be empty │ Input given key is an empty string. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage node address not found │ There is no node that stores the given key. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage does not exist │ The storage cannot be found on the designated node. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key has expired │ The given key has expired, but not yet deleted from the memory. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key does not exists │ The given key does not exist in the storage. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Network errors │ Internal network error such as reliable communication time out etc. │ └────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
The possible error evaluations:
Besides the following errors, there are Mesh module errors as well.
dive.IsSetupError(err error) // Dive has not been setup dive.IsInvalidStorageNameError(err error) // Invalid storage name dive.IsInvalidKeyError(err error) // Invalid or empty key provided dive.IsNodeNotFoundError(err error) // Dive storage server node not found dive.IsNodeAddressNotFoundError(err error) // Dive storage server node address not found by the given key dive.IsPopError(err error) // Dive Pop failure
▶︎ Return Data
The function returns an instance of *Result. To retrieve the data according to the correct data type, *Result has To...() functions.
Example:
// If the intended result value is an array of strings
result, err := storage.RPop(key, 10)
if err != nil {
// handle error...
}
int64List, err := result.ToInt64Array()
if err != nil {
// the value is not int64 array...
}
Parameters
key - The key of the value to retrieve.
howmany - Number of elements from the list set to pop.
If the number is greater than the length of the list set, it will pop all elements.
If 0 or below given, the entire list will be popped.
func (s *Storage) RPopEx(key string, howmany int, ttl uint32) (*Result, error)
RPopEx returns an array of elements from the list set created by LPush and/or RPush from the last element up to the number given by howmany in reverse order.
The returned elements will be atomically removed from the list set.
[IMPORTANT] The function uses mutex lock internally. [IMPORTANT] The function is asynchronous internally and accesses a remote node in the Diarkis cluster. [IMPORTANT] The function may fail during key migration.
Error Cases
┌────────────────────────────────┬───────────────────────────────────────────────────────────────────────┐ │ Error │ Reason │ ╞════════════════════════════════╪═══════════════════════════════════════════════════════════════════════╡ │ Setup must be invoked │ In order to use Dive module, │ │ │ dive.Setup() must be called before calling diarkis.Start() │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key must not be empty │ Input given key is an empty string. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage node address not found │ There is no node that stores the given key. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage does not exist │ The storage cannot be found on the designated node. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key has expired │ The given key has expired, but not yet deleted from the memory. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key does not exists │ The given key does not exist in the storage. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ TTL exceeds 86400 s │ TTL must not exceed 86400 s (24 hours). │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Network errors │ Internal network error such as reliable communication time out etc. │ └────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
The possible error evaluations:
Besides the following errors, there are Mesh module errors as well.
dive.IsSetupError(err error) // Dive has not been setup dive.IsInvalidStorageNameError(err error) // Invalid storage name dive.IsInvalidKeyError(err error) // Invalid or empty key provided dive.IsNodeNotFoundError(err error) // Dive storage server node not found dive.IsNodeAddressNotFoundError(err error) // Dive storage server node address not found by the given key dive.IsInvalidTTLError(err error) // Provided TTL is invalid dive.IsPopError(err error) // Dive Pop failure
▶︎ Return Data
The function returns an instance of *Result. To retrieve the data according to the correct data type, *Result has To...() functions.
Example:
// If the intended result value is an array of strings
result, err := storage.RPopEx(key, 10, ttl)
if err != nil {
// handle error...
}
int64List, err := result.ToInt64Array()
if err != nil {
// the value is not int64 array...
}
Parameters
key - The key of the value to retrieve.
howmany - Number of elements from the list set to pop.
If the number is greater than the length of the list set, it will pop all elements.
If 0 or below given, the entire list will be popped.
ttl - If greater than 0, TTL of the key will be extended.
TTL must not exceed 86400. TTL is in seconds.
func (s *Storage) RPush(key string, values ...[]byte) error
RPush stores a value as an element of a list associated to the given key on a node derived from the given key and assigns a TTL for the key and value to expire.
The value as an element is pushed to the end of the array and it updates internal timestamp and TTL.
[CRITICALLY IMPORTANT] The value must NOT be struct or contain struct.
[IMPORTANT] The function uses mutex lock internally.
[IMPORTANT] Value data type must be either primitive, string, or []byte.
[IMPORTANT] The function is asynchronous internally and accesses a remote node in the Diarkis cluster.
[IMPORTANT] The key WILL expire in 24 hours.
Default TTL can be configured to be other than 24 hours.
[IMPORTANT] Every RPush updates TTL of the key.
Error Cases
┌────────────────────────────────┬───────────────────────────────────────────────────────────────────────┐ │ Error │ Reason │ ╞════════════════════════════════╪═══════════════════════════════════════════════════════════════════════╡ │ Setup must be invoked │ In order to use Dive module, │ │ │ dive.Setup() must be called before calling diarkis.Start() │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key must not be empty │ Input given key is an empty string. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage node address not found │ There is no node that stores the given key. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage does not exist │ The storage cannot be found on the designated node. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key already exists │ The given key already exists. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Network errors │ Internal network error such as reliable communication time out etc. │ └────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
The possible error evaluations:
Besides the following errors, there are Mesh module errors as well.
dive.IsSetupError(err error) // Dive has not been setup dive.IsInvalidStorageNameError(err error) // Invalid storage name dive.IsInvalidKeyError(err error) // Invalid or empty key provided dive.IsNodeNotFoundError(err error) // Dive storage server node not found dive.IsNodeAddressNotFoundError(err error) // Dive storage server node address not found by the given key dive.IsPushError(err error) // Dive Push failure
Parameters
key - The key of the given value to be stored.
value - Value of the given key to be stored.
You may pass multiple values to push multiple elements to the list set.
Examples:
RPush(key, 1, 2, 3)
RPush(key, []interface{}{1, 2, 3}...)
func (s *Storage) RPushEx(key string, ttl uint32, values ...[]byte) error
RPushEx stores a value as an element of a list associated to the given key on a node derived from the given key and assigns a TTL for the key and value to expire.
The value as an element is pushed to the end of the array and it updates internal timestamp and TTL.
[CRITICALLY IMPORTANT] The value must NOT be struct or contain struct. [IMPORTANT] The function uses mutex lock internally. [IMPORTANT] Value data type must be either primitive, string, or []byte. [IMPORTANT] The function is asynchronous internally and accesses a remote node in the Diarkis cluster. [IMPORTANT] Every RPushEX updates TTL of the key.
Error Cases
┌────────────────────────────────┬───────────────────────────────────────────────────────────────────────┐ │ Error │ Reason │ ╞════════════════════════════════╪═══════════════════════════════════════════════════════════════════════╡ │ Setup must be invoked │ In order to use Dive module, │ │ │ dive.Setup() must be called before calling diarkis.Start() │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key must not be empty │ Input given key is an empty string. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ TTL must not be 0 │ TTL must be greater than 0 second. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage node address not found │ There is no node that stores the given key. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage does not exist │ The storage cannot be found on the designated node. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key already exists │ The given key already exists. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ TTL exceeds 86400 ms │ TTL must not exceed 86400 ms (24 hours). │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Network errors │ Internal network error such as reliable communication time out etc. │ └────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
The possible error evaluations:
Besides the following errors, there are Mesh module errors as well.
dive.IsSetupError(err error) // Dive has not been setup dive.IsInvalidStorageNameError(err error) // Invalid storage name dive.IsInvalidKeyError(err error) // Invalid or empty key provided dive.IsNodeNotFoundError(err error) // Dive storage server node not found dive.IsNodeAddressNotFoundError(err error) // Dive storage server node address not found by the given key dive.IsInvalidTTLError(err error) // Provided TTL is invalid dive.IsPushError(err error) // Dive Push failure
Parameters
key - The key of the given value to be stored.
ttl - TTL in seconds for the key and value pair to expire.
If greater than 0 is given, TTL of the key will be extended.
TTL must not exceed 86400. TTL is in seconds.
value - Value of the given key to be stored.
You may pass multiple values to push multiple elements to the list set.
Examples:
RPushEx(key, 1, 2, 3)
RPushEx(key, []interface{}{1, 2, 3}...)
func (s *Storage) RemoveOnNodeChange(cb func()) bool
RemoveOnNodeChange removes the assigned callback.
func (s *Storage) ResolveKey(key string) string
ResolveKey returns the associated internal server node address of the given key.
func (s *Storage) Set(key string, value []byte) error
Set stores the key value pair on a node derived from the given key.
[CRITICALLY IMPORTANT] The value must NOT be struct or contain struct.
[IMPORTANT] The function uses mutex lock internally.
[IMPORTANT] Value data type must be either primitive, string, or []byte.
[IMPORTANT] The function is asynchronous internally and accesses a remote node in the Diarkis cluster.
[IMPORTANT] The key and value pair WILL expire in 24 hours.
Default TTL can be configured to be other than 24 hours.
Error Cases
┌────────────────────────────────┬───────────────────────────────────────────────────────────────────────┐ │ Error │ Reason │ ╞════════════════════════════════╪═══════════════════════════════════════════════════════════════════════╡ │ Setup must be invoked │ In order to use Dive module, │ │ │ dive.Setup() must be called before calling diarkis.Start() │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key must not be empty │ Input given key is an empty string. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage node address not found │ There is no node that stores the given key. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage does not exist │ The storage cannot be found on the designated node. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Invalid data type │ The value to increment must be of type int32. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Network errors │ Internal network error such as reliable communication time out etc. │ └────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
The possible error evaluations:
Besides the following errors, there are Mesh module errors as well.
dive.IsSetupError(err error) // Dive has not been setup dive.IsInvalidKeyError(err error) // Invalid or empty key provided dive.IsNodeNotFoundError(err error) // Dive storage server node not found dive.IsNodeAddressNotFoundError(err error) // Dive storage server node address not found by the given key dive.IsInvalidValueTypeError(err error) // Provided value type is invalid dive.IsSetError(err error) // Dive Set failure
Parameters
key - The key of the given value to be stored. value - Value of the given key to be stored.
func (s *Storage) SetChangeRingSizeOnNodeUpdate(cb func(int) uint32) bool
SetChangeRingSizeOnNodeUpdate assigns a callback to change ring size before node update.
func (s *Storage) SetEx(key string, value []byte, ttl uint32) error
SetEx stores the key value pair on a node derived from the given key and assigns a TTL in seconds.
[CRITICALLY IMPORTANT] The value must NOT be struct or contain struct. [IMPORTANT] The function uses mutex lock internally. [IMPORTANT] Value data type must be either primitive, string, or []byte. [IMPORTANT] The function is asynchronous internally and accesses a remote node in the Diarkis cluster.
Error Cases
┌────────────────────────────────┬───────────────────────────────────────────────────────────────────────┐ │ Error │ Reason │ ╞════════════════════════════════╪═══════════════════════════════════════════════════════════════════════╡ │ Setup must be invoked │ In order to use Dive module, │ │ │ dive.Setup() must be called before calling diarkis.Start() │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key must not be empty │ Input given key is an empty string. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ TTL must not be 0 │ TTL must be greater than 0 second. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage node address not found │ There is no node that stores the given key. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage does not exist │ The storage cannot be found on the designated node. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Network errors │ Internal network error such as reliable communication time out etc. │ └────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
The possible error evaluations:
Besides the following errors, there are Mesh module errors as well.
dive.IsSetupError(err error) // Dive has not been setup dive.IsInvalidKeyError(err error) // Invalid or empty key provided dive.IsNodeNotFoundError(err error) // Dive storage server node not found dive.IsNodeAddressNotFoundError(err error) // Dive storage server node address not found by the given key dive.IsInvalidValueTypeError(err error) // Provided value type is invalid dive.IsInvalidTTLError(err error) // Provided TTL is invalid dive.IsSetError(err error) // Dive Set failure
Parameters
key - The key of the given value to be stored. value - Value of the given key to be stored. ttl - TTL in seconds for the key and value pair to expire.
func (s *Storage) SetIfNotExists(key string, value []byte) error
SetIfNotExists stores the key value pair on a node derived from the given key.
[CRITICALLY IMPORTANT] The value must NOT be struct or contain struct.
[IMPORTANT] The function uses mutex lock internally.
[IMPORTANT] Value data type must be either primitive, string, or []byte.
[IMPORTANT] The function is asynchronous internally and accesses a remote node in the Diarkis cluster.
[IMPORTANT] The key and value pair WILL expire in 24 hours.
Default TTL can be configured to be other than 24 hours.
Error Cases
┌────────────────────────────────┬───────────────────────────────────────────────────────────────────────┐ │ Error │ Reason │ ╞════════════════════════════════╪═══════════════════════════════════════════════════════════════════════╡ │ Setup must be invoked │ In order to use Dive module, │ │ │ dive.Setup() must be called before calling diarkis.Start() │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key must not be empty │ Input given key is an empty string. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage node address not found │ There is no node that stores the given key. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage does not exist │ The storage cannot be found on the designated node. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key already exists │ The given key already exists. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Network errors │ Internal network error such as reliable communication time out etc. │ └────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
The possible error evaluations:
Besides the following errors, there are Mesh module errors as well.
dive.IsSetupError(err error) // Dive has not been setup dive.IsInvalidKeyError(err error) // Invalid or empty key provided dive.IsNodeNotFoundError(err error) // Dive storage server node not found dive.IsNodeAddressNotFoundError(err error) // Dive storage server node address not found by the given key dive.IsInvalidValueTypeError(err error) // Provided value type is invalid dive.IsSetIfNotExistError(err error) // Dive SetIfNotExist failure
Parameters
key - The key of the given value to be stored. value - Value of the given key to be stored.
func (s *Storage) SetIfNotExistsEx(key string, value []byte, ttl uint32) error
SetIfNotExistsEx stores the key value pair on a node derived from the given key and assigns a TTL for the key and value to expire.
[CRITICALLY IMPORTANT] The value must NOT be struct or contain struct. [IMPORTANT] The function uses mutex lock internally. [IMPORTANT] Value data type must be either primitive, string, or []byte. [IMPORTANT] The function is asynchronous internally and accesses a remote node in the Diarkis cluster.
Error Cases
┌────────────────────────────────┬───────────────────────────────────────────────────────────────────────┐ │ Error │ Reason │ ╞════════════════════════════════╪═══════════════════════════════════════════════════════════════════════╡ │ Setup must be invoked │ In order to use Dive module, │ │ │ dive.Setup() must be called before calling diarkis.Start() │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key must not be empty │ Input given key is an empty string. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ TTL must not be 0 │ TTL must be greater than 0 second. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage node address not found │ There is no node that stores the given key. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Storage does not exist │ The storage cannot be found on the designated node. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Key already exists │ The given key already exists. │ ├────────────────────────────────┼───────────────────────────────────────────────────────────────────────┤ │ Network errors │ Internal network error such as reliable communication time out etc. │ └────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
The possible error evaluations:
Besides the following errors, there are Mesh module errors as well.
dive.IsSetupError(err error) // Dive has not been setup dive.IsInvalidKeyError(err error) // Invalid or empty key provided dive.IsNodeNotFoundError(err error) // Dive storage server node not found dive.IsNodeAddressNotFoundError(err error) // Dive storage server node address not found by the given key dive.IsInvalidValueTypeError(err error) // Provided value type is invalid dive.IsInvalidTTLError(err error) // Provided TTL is invalid dive.IsSetIfNotExistError(err error) // Dive SetIfNotExist failure
Parameters
key - The key of the given value to be stored. value - Value of the given key to be stored. ttl - TTL in seconds for the key and value pair to expire.
func (s *Storage) SetOnLRange(cb func(list [][]byte) [][]byte) bool
SetOnLRange assigns a callback to be invoked on every LRange.
[IMPORTANT] This callback must be assigned on the target node server.
Default target node server is HTTP, but it can be configured to something else.
[IMPORTANT] This function is not goroutine safe. It means that it should be used only during the setup of the server.
[IMPORTANT] The callback receives an array of interface{} NOT *Result.
In order to handle each interface{} element, you must use util module's To...() function.
Example:
assigned := storage.SetOnLRange(func(list []interface{}) []interface{} {
for i := 0; i < len(list); i++ {
value, ok := util.ToFloat32(list[i])
}
})
Parameters
cb - Callback function to be executed on every LRange.
The callback will be passed the entire list data and the returned list data will be the returned value of LRange.
func (s *Storage) SetOnNodeChange(cb func())
SetOnNodeChange assigns a callback to be invoked when the number of target node server changes.
[NOTE] The callbacks will be called regardless of migration being enabled or not.
func (s *Storage) SetOnPush(cb func(key string, list [][]byte) [][]byte) bool
SetOnPush assigns a callback to be invoked on every LPush and RPush.
[IMPORTANT] This callback must be assigned on the target node server.
Default target node server is HTTP, but it can be configured to something else.
[IMPORTANT] This function is not goroutine safe. It means that it should be used only during the setup of the server.
[IMPORTANT] The callback is invoked while the mutex lock is held. You must avoid using mutex lock in the callback to avoid mutex deadlock.
[IMPORTANT] The callback receives an array of interface{} NOT *Result.
In order to handle each interface{} element, you must use util module's To...() function.
Example:
assigned := storage.SetOnPush(storageName, func(list []interface{}) []interface{} {
for i := 0; i < len(list); i++ {
value, ok := util.ToFloat32(list[i])
}
})
Parameters
cb - Callback function to be executed on every LPush and RPush.
The callback will be passed the entire list data and the returned list data will be stored on the storage.
func (s *Storage) UpdateRingSize(ringSize uint32)
UpdateRingSize changes the ring size.
[IMPORTANT] Changing the ring size will change the key to address index calculation.
It means that the same keys may point to different servers leading to values of keys not being found etc.