package dive

import "github.com/Diarkis/diarkis/dive"

Package dive ▷

Distributed Vault Engine → DIVE

Dive module creates a distributed memory storages within the Diarkis cluster.

The module is accessible from anywhere as long as it is within the cluster.

Each storage is separated by name and each distributes the key value pairs across all servers with the targeted server type (targetNodeType) so that the key value pairs are distributed and scalable.

Dive storages enable you to set and get keys and their values from anywhere within the Diarkis cluster. 

[IMPORTANT] Dive module stores key value pairs in memory and they are not persisted.

Target node type

Dive module requires you to specify which node type (HTTP, UDP, TCP, or custom type) to act as storage.

By default, targtNodeType is HTTP.

Configurations

You must configure each storage by its name in order to use Dive module.

The configured storages are available on every server node with the configurations via dive.GetStorageByName("$(storage_name)") *dive.Storage 

"storages": {
  "$(storage_name)": {
    "targetNodeType": "HTTP",
    "multipleIndex": 1,
    "ringSize": 300,
    "cleanInterval": 300,
    "defaultTTL": 8640,
    "migration": true,
    "migrationBatchSize": 100,
    "migrationInterval": 1000,
  }
}

Optional Configurations per Storage 

storages.$(storage_name).multipleIndex      - Each Dive node (server) has at least one index internally assigned.
                                              By increasing the number you may assign multiple indexes to each node.
                                              Default is 1.

storages.$(storage_name).targetNodeType     - Target node type determines the storage to use which servers as storage: Default is HTTP

storages.$(storage_name).ringSize           - Ring size determines the hash ring size of the storage: Default is 300
                                              Ring size determines the hash range
                                              and it must be greater than the number of nodes.

storage.$(storage_name).cleanInterval       - Interval in seconds for cleaning up expired keys from the storage memory.
                                              Default is 5 minutes.
                                              Configuring this value to be very small will have negative effect on CPU performance.

storage.$(storage_name).defaultTTL          - Default TTL of keys stored by Set and SetIfNotExists in seconds.
                                              Default is 24 hours.

storages.$(storage_name).migration          - Enables or Disables key migration when scaling: Default is true

storages.$(storage_name).migrationBatchSize - Number of keys to be batched and migrated at a time.
                                              Setting is value large will make the migration time shorter,
                                              but setting the value too large may cause each migration packet
                                              to split and slow down the migration instead:
                                              Default is 10.

storages.$(storage_name).migrationInterval  - Interval in milliseconds for each migration batch (server-to-server key transfer) to be sent:
                                              Default is 1ms.
                                              Longer this value is the longer it takes to complete migration, but less server stress.

Example Configurations 

"storages": {
  "MyAwesomeDiveStorage": {
    "targetNodeType": "HTTP",
    "ringSize": 300,
    "cleanInterval": 3000,
    "defaultTTL": 60000,
    "migration": true,
    "migrationBatchSize": 10,
    "migrationInterval": 1000,
  }
}

▶︎ How to access the configured storage: 

storage := dive.GetStorageByName("MyAwesomeDiveStorage")

Setting Up Dive Module

In order to setup Dive module correctly, dive.Setup(...) must be called AFTER mesh.Setup() and server.SetupAs...() functions.

Distribution of Key Value Data

Dive module storages distribute key value data throughout the target node nodes.

▶︎ Scaling of server nodes

When the number of nodes change each node re-distributes the key value data to new nodes and this may take some time depending on the number of keys.

During the re-distribution of keys, the storage locks the operations, so that Storage.Set, Storage.Get, and Storage.Del will wait until the re-distribution is finished.

▶︎ Shrinking of server nodes

When some nodes are to shutdown, the nodes will re-distribute the keys to other available nodes.

Key Migration

When the number of target node servers change, all keys will be re-distributed to appropriate server node. 

[IMPORTANT] If one attempts to retrieve a key that is being migrated, it will return an error until the key completes its migration.

[IMPORTANT] Server node that is shutting down will not shutdown until all of its keys are migrated to other server nodes.

Key Removal and TTL

Keys that are stored by Storage.Set and Storage.SetIfNotExists will have TTL of default value. If it is not configured specifically, the default TTL is 24 hours.

With Storage.SetEx, Storage.SetIfNotExistsEx, Storage.LPushEx, and Storage.RPushEx, you may assign your custom TTL in seconds. 

[IMPORTANT] A very short TTL, in most cases, is pointless.

[IMPORTANT] All keys have TTL and they will be expired.

The expired keys are NOT removed from the memory immediately, each storage has its own cleaning operation that is executed at a certain interval to remove expired keys from the memory.

Server Node Crush

When a node crushes unexpectedly, the keys and their values on the crushed server node will be lost.

▶︎ Debug Key Dump

Dive module has a way of outputting all keys on a server to stdout stream for debugging purpose.

1. Create a signal command file named DIARKIS_SIGUSR1 under /tmp/ directory. It should look like this: /tmp/DIARKIS_SIGUSR1

2. Write DiveKeyDump in DIARKIS_SIGUSR1 file

3. Send a SIGUSR1 signal to the target Diarkis server process.

4. This will dump all keys to stdout stream for debugging.

Index

Functions

func IsDelError

func IsDelError(err error) bool

IsDelError returns true if the given error is or contains DiveDeleteError error.

func IsDuplicateStorageError

func IsDuplicateStorageError(err error) bool

IsDuplicateStorageError returns true if the given error is or contains DiveDuplicateStorageError error.

func IsGetError

func IsGetError(err error) bool

IsGetError returns true if the given error is or contains DiveGetError error.

func IsIncrError

func IsIncrError(err error) bool

IsIncrError returns true if the given error is or contains DiveIncrError error.

func IsInvalidKeyError

func IsInvalidKeyError(err error) bool

IsInvalidKeyError returns true if the given error is or contains DiveInvalidKeyError error.

func IsInvalidRangeParametersError

func IsInvalidRangeParametersError(err error) bool

IsInvalidRangeParametersError returns true if the given error is or contains DiveInvalidRangeParametersError error.

func IsInvalidStorageNameError

func IsInvalidStorageNameError(err error) bool

IsInvalidStorageNameError returns true if the given error is or contains DiveInvalidStorageNameError error.

func IsInvalidTTLError

func IsInvalidTTLError(err error) bool

IsInvalidTTLError returns true if the given error is or contains DiveInvalidTTLError error.

func IsInvalidValueTypeError

func IsInvalidValueTypeError(err error) bool

IsInvalidValueTypeError returns true if the given error is or contains DiveInvalidValueTypeError error.

func IsKeyExpiredError

func IsKeyExpiredError(err error) bool

IsKeyExpiredError returns true if the given error is or contains DiveKeyExpiredError error.

func IsNewStorageError

func IsNewStorageError(err error) bool

IsNewStorageError returns true if the given error is or contains DiveNewStorageError error.

func IsNodeAddressNotFoundError

func IsNodeAddressNotFoundError(err error) bool

IsNodeAddressNotFoundError returns true if the given error is or contains DiveNodeAddressNotFoundError error.

func IsNodeNotFoundError

func IsNodeNotFoundError(err error) bool

IsNodeNotFoundError returns true if the given error is or contains DiveNodeNotFoundError error.

func IsPopError

func IsPopError(err error) bool

IsPopError returns true if the given error is or contains DivePopError error.

func IsPushError

func IsPushError(err error) bool

IsPushError returns true if the given error is or contains DivePushError error.

func IsRangeError

func IsRangeError(err error) bool

IsRangeError returns true if the given error is or contains DiveRangeError error.

func IsReady

func IsReady() bool

IsReady returns true if Dive module is ready.

func IsReadyToShutdown

func IsReadyToShutdown() bool

IsReadyToShutdown returns true when Dive module is ready to shutdown. 

[NOTE] This function is used internally.

func IsSetError

func IsSetError(err error) bool

IsSetError returns true if the given error is or contains DiveSetError error.

func IsSetIfNotExistError

func IsSetIfNotExistError(err error) bool

IsSetIfNotExistError returns true if the given error is or contains DiveSetIfNotExistError error.

func IsSetUp

func IsSetUp() bool

IsSetUp returns true if Dive module is setup.

func IsSetupError

func IsSetupError(err error) bool

IsSetupError returns true if the given error is or contains DiveSetupError error.

func SetOnLRangeByStorageName

func SetOnLRangeByStorageName(name string, cb func(list [][]byte) [][]byte) bool

SetOnLRangeByStorageName assigns a callback to be invoked on every Storage.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.

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

func SetOnPushByStorageName(name string, cb func(key string, list [][]byte) [][]byte) bool

SetOnPushByStorageName assigns a callback to be invoked on every Storage.LPush and Storage.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.

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

func SetOnReady(cb func())

SetOnReady assigns a callback to be invoked when Dive module is ready.

func Setup

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.

func SetupStorages

func SetupStorages(confpath string)

SetupStorages reads the configuration file and creates storages.

Types

type ChangeRingSizeFunc

type ChangeRingSizeFunc func(int) uint32

ChangeRingSizeFunc is a callback for calculating a new ring size based on the node count.

type Options

type Options struct {
	MultipleIndex      uint8
	RingSize           uint32
	TargetNodeType     string
	Migration          bool
	MigrationBatchSize uint16
	MigrationInterval  uint16
}

Options represents optional configurations for New(name string, options *Options) to create a new storage without the use of configuration file.

type Result

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

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.

func (*Result) IsError

func (r *Result) IsError() bool

IsError returns true if the result is an error.

You may retrieve the error by calling Result.ToError().

func (*Result) ToBool

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToBoolArray

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToBytes

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.

Example of Using td.TransportData

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)
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToBytesArray

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToError

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 Result.IsError().

func (*Result) ToFloat32

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToFloat32Array

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToFloat64

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToFloat64Array

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToInt16

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToInt16Array

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToInt32

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToInt32Array

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToInt64

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToInt64Array

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToInt8

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToInt8Array

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToString

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToStringArray

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToUint16

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 (*Result) ToUint16Array

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToUint32

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToUint32Array

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToUint64

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToUint64Array

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToUint8

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

func (*Result) ToUint8Array

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.
Error

If the value data type is not what is asked for, it will error out. 

dive.IsInvalidValueTypeError(err error)

type Storage

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

Storage represents the distributed data storage within Diarkis cluster.

func GetStorageByName

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

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 (*Storage) Del

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.     │
└────────────────────────────────┴─────────────────────────────────────────────────────────────────────────┘
Error Evaluations

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 (*Storage) Get

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.   │
└────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
Error Evaluations

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 (*Storage) GetEx

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.   │
└────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
Error Evaluations

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 (*Storage) GetLocalKeys

func (s *Storage) GetLocalKeys() []string

GetLocalKeys returns an array of locally stored keys.

func (*Storage) GetNumberOfNodes

func (s *Storage) GetNumberOfNodes() int

GetNumberOfNodes returns the number of recognized nodes for Dive.

func (*Storage) IncrBy

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.
Error Evaluations

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 (*Storage) IncrByEx

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.
Error Evaluations

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 (*Storage) IsStorage

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 (*Storage) LPop

func (s *Storage) LPop(key string, howmany int) (*Result, error)

LPop returns an array of elements from the list set created by Storage.LPush and/or Storage.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.   │
└────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
Error Evaluations

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 (*Storage) LPopEx

func (s *Storage) LPopEx(key string, howmany int, ttl uint32) (*Result, error)

LPopEx returns an array of elements from the list set created by Storage.LPush and/or Storage.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.   │
└────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
Error Evaluations

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 (*Storage) LPush

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. 

[IMPORTANT] The function uses mutex lock internally.
[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.   │
└────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
Error Evaluations

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, []byte{1}, []byte{2}, []byte{3})

func (*Storage) LPushEx

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. 

[IMPORTANT] The function uses mutex lock internally.
[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.   │
└────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
Error Evaluations

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, 10, []byte{1}, []byte{2}, []byte{3})

func (*Storage) LRange

func (s *Storage) LRange(key string, from, to int) *Result

LRange retrieves the value of the given key as an array. Storage.LRange can only work with either Storage.LPush or Storage.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.   │
└────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
Error Evaluations

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 (*Storage) LRangeEx

func (s *Storage) LRangeEx(key string, from, to int, ttl uint32) *Result

LRangeEx retrieves the value of the given key as an array. Storage.LRange can only work with either Storage.LPush or Storage.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.   │
└────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
Error Evaluations

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 (*Storage) RPop

func (s *Storage) RPop(key string, howmany int) (*Result, error)

RPop returns an array of elements from the list set created by Storage.LPush and/or Storage.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.   │
└────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
Error Evaluations

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 (*Storage) RPopEx

func (s *Storage) RPopEx(key string, howmany int, ttl uint32) (*Result, error)

RPopEx returns an array of elements from the list set created by Storage.LPush and/or Storage.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.   │
└────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
Error Evaluations

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 (*Storage) RPush

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. 

[IMPORTANT] The function uses mutex lock internally.
[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.   │
└────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
Error Evaluations

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, []byte{1}, []byte{2}, []byte{3})

func (*Storage) RPushEx

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. 

[IMPORTANT] The function uses mutex lock internally.
[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.   │
└────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
Error Evaluations

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, 10, []byte{1}, []byte{2}, []byte{3})

func (*Storage) RemoveOnNodeChange

func (s *Storage) RemoveOnNodeChange(cb func()) bool

RemoveOnNodeChange removes the assigned callback.

func (*Storage) ResolveKey

func (s *Storage) ResolveKey(key string) string

ResolveKey returns the associated internal server node address of the given key.

func (*Storage) Set

func (s *Storage) Set(key string, value []byte) error

Set stores the key value pair on a node derived from 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 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.   │
└────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
Error Evaluations

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 (*Storage) SetChangeRingSizeOnNodeUpdate

func (s *Storage) SetChangeRingSizeOnNodeUpdate(cb ChangeRingSizeFunc) bool

SetChangeRingSizeOnNodeUpdate assigns a callback to change ring size before node update.

func (*Storage) SetEx

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. 

[IMPORTANT] The function uses mutex lock internally.
[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.   │
└────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
Error Evaluations

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 (*Storage) SetIfNotExists

func (s *Storage) SetIfNotExists(key string, value []byte) error

SetIfNotExists stores the key value pair on a node derived from 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 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.   │
└────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
Error Evaluations

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 (*Storage) SetIfNotExistsEx

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. 

[IMPORTANT]            The function uses mutex lock internally.
[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.   │
└────────────────────────────────┴───────────────────────────────────────────────────────────────────────┘
Error Evaluations

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 (*Storage) SetOnLRange

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.

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 (*Storage) SetOnNodeChange

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 (*Storage) SetOnPush

func (s *Storage) SetOnPush(cb func(key string, list [][]byte) [][]byte) bool

SetOnPush assigns a callback to be invoked on every Storage.LPush and Storage.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.

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 (*Storage) UpdateRingSize

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.