client

README

client

A Go client library to integrate applications with god/dhash.

Usage

Install with go get:

go get github.com/zond/god/client

Then import into your Go project:

import "github.com/zond/god/client"

For examples see https://github.com/zond/god/blob/master/client/client_test.go

Documentation

Index

• type Conn
  • func MustConn(addr string) (result *Conn)
  • func NewConn(addr string) (result *Conn, err error)
  • func NewConnRing(ring *common.Ring) *Conn
  • func (self *Conn) AddConfiguration(key, value string)
  • func (self *Conn) Clear()
  • func (self *Conn) Configuration() (conf map[string]string)
  • func (self *Conn) Count(key, min, max []byte, mininc, maxinc bool) (result int)
  • func (self *Conn) Del(key []byte)
  • func (self *Conn) Describe() string
  • func (self *Conn) DescribeAllNodes() (result []common.DHashDescription)
  • func (self *Conn) DescribeAllTrees() string
  • func (self *Conn) DescribeNode(pos []byte) (result common.DHashDescription, err error)
  • func (self *Conn) DescribeTree(pos []byte) (result string, err error)
  • func (self *Conn) Dump() (c chan [2][]byte, wait *sync.WaitGroup)
  • func (self *Conn) First(key []byte) (firstKey, firstValue []byte, existed bool)
  • func (self *Conn) Get(key []byte) (value []byte, existed bool)
  • func (self *Conn) IndexOf(key, subKey []byte) (index int, existed bool)
  • func (self *Conn) Last(key []byte) (lastKey, lastValue []byte, existed bool)
  • func (self *Conn) MirrorCount(key, min, max []byte, mininc, maxinc bool) (result int)
  • func (self *Conn) MirrorFirst(key []byte) (firstKey, firstValue []byte, existed bool)
  • func (self *Conn) MirrorIndexOf(key, subKey []byte) (index int, existed bool)
  • func (self *Conn) MirrorLast(key []byte) (lastKey, lastValue []byte, existed bool)
  • func (self *Conn) MirrorNextIndex(key []byte, index int) (foundKey, foundValue []byte, foundIndex int, existed bool)
  • func (self *Conn) MirrorPrevIndex(key []byte, index int) (foundKey, foundValue []byte, foundIndex int, existed bool)
  • func (self *Conn) MirrorReverseIndexOf(key, subKey []byte) (index int, existed bool)
  • func (self *Conn) MirrorReverseSlice(key, min, max []byte, mininc, maxinc bool) (result []common.Item)
  • func (self *Conn) MirrorReverseSliceIndex(key []byte, min, max *int) (result []common.Item)
  • func (self *Conn) MirrorReverseSliceLen(key, max []byte, maxinc bool, maxRes int) (result []common.Item)
  • func (self *Conn) MirrorSlice(key, min, max []byte, mininc, maxinc bool) (result []common.Item)
  • func (self *Conn) MirrorSliceIndex(key []byte, min, max *int) (result []common.Item)
  • func (self *Conn) MirrorSliceLen(key, min []byte, mininc bool, maxRes int) (result []common.Item)
  • func (self *Conn) Next(key []byte) (nextKey, nextValue []byte, existed bool)
  • func (self *Conn) NextIndex(key []byte, index int) (foundKey, foundValue []byte, foundIndex int, existed bool)
  • func (self *Conn) Nodes() common.Remotes
  • func (self *Conn) Prev(key []byte) (prevKey, prevValue []byte, existed bool)
  • func (self *Conn) PrevIndex(key []byte, index int) (foundKey, foundValue []byte, foundIndex int, existed bool)
  • func (self *Conn) Put(key, value []byte)
  • func (self *Conn) Reconnect()
  • func (self *Conn) ReverseIndexOf(key, subKey []byte) (index int, existed bool)
  • func (self *Conn) ReverseSlice(key, min, max []byte, mininc, maxinc bool) (result []common.Item)
  • func (self *Conn) ReverseSliceIndex(key []byte, min, max *int) (result []common.Item)
  • func (self *Conn) ReverseSliceLen(key, max []byte, maxinc bool, maxRes int) (result []common.Item)
  • func (self *Conn) SDel(key []byte)
  • func (self *Conn) SPut(key, value []byte)
  • func (self *Conn) SSubClear(key []byte)
  • func (self *Conn) SSubDel(key, subKey []byte)
  • func (self *Conn) SSubPut(key, subKey, value []byte)
  • func (self *Conn) SetExpression(expr setop.SetExpression) (result []setop.SetOpResult)
  • func (self *Conn) Size() (result int)
  • func (self *Conn) Slice(key, min, max []byte, mininc, maxinc bool) (result []common.Item)
  • func (self *Conn) SliceIndex(key []byte, min, max *int) (result []common.Item)
  • func (self *Conn) SliceLen(key, min []byte, mininc bool, maxRes int) (result []common.Item)
  • func (self *Conn) Start()
  • func (self *Conn) SubAddConfiguration(treeKey []byte, key, value string)
  • func (self *Conn) SubClear(key []byte)
  • func (self *Conn) SubConfiguration(key []byte) (conf map[string]string)
  • func (self *Conn) SubDel(key, subKey []byte)
  • func (self *Conn) SubDump(key []byte) (c chan [2][]byte, wait *sync.WaitGroup)
  • func (self *Conn) SubGet(key, subKey []byte) (value []byte, existed bool)
  • func (self *Conn) SubMirrorNext(key, subKey []byte) (nextKey, nextValue []byte, existed bool)
  • func (self *Conn) SubMirrorPrev(key, subKey []byte) (prevKey, prevValue []byte, existed bool)
  • func (self *Conn) SubNext(key, subKey []byte) (nextKey, nextValue []byte, existed bool)
  • func (self *Conn) SubPrev(key, subKey []byte) (prevKey, prevValue []byte, existed bool)
  • func (self *Conn) SubPut(key, subKey, value []byte)
  • func (self *Conn) SubSize(key []byte) (result int)

Types

type Conn

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

Conn is the client connection.

A god database has two data types: byte values and sub trees. All values are sorted in ascending order.

Byte values are simply byte slices indexed by a key byte slice.

Sub trees are trees containing byte values.

Sub trees can be 'mirrored', which means that they contain a tree mirroring its values as keys and its keys as values. To mirror a sub tree, call SubAddConfiguration for the sub tree and set 'mirrored' to 'yes'.

Naming conventions:

If there are two methods with similar names except that one has a capital S prefixed, that means that the method with the capital S will not return until all nodes responsible for the written data has received the data, while the one without the capital S will return as soon as the owner of the data has received it.

Methods prefixed Sub will work on sub trees.

Methods prefixed Reverse will work in reverse order. Return slices in reverse order and indices from the end instead of the start etc.

Methods prefixed Mirror will work on the mirror trees of the sub trees in question.

Parameters named mininc and maxinc paired with parameters min and max of []byte type defined whether the min and max parameters are inclusive as opposed to exclusive.

To install: go get github.com/zond/god/client

Usage: https://github.com/zond/god/blob/master/client/client_test.go

func MustConn

func MustConn(addr string) (result *Conn)

MustConn creates a working Conn or panics.

func NewConn

func NewConn(addr string) (result *Conn, err error)

NewConn creates a new Conn to a cluster defined by the address of one of its members.

func NewConnRing

func NewConnRing(ring *common.Ring) *Conn

NewConnRing creates a new Conn from a given set of known nodes. For internal usage.

func (*Conn) AddConfiguration

func (self *Conn) AddConfiguration(key, value string)

AddConfiguration will set a key and value to the cluster configuration. Not internally used for anything right now.

func (*Conn) Clear

func (self *Conn) Clear()

Clear will remove all data from all currently known database nodes.

func (*Conn) Configuration

func (self *Conn) Configuration() (conf map[string]string)

Configuration will return the configuration for the entire cluster. Not internally used for anything right now.

func (*Conn) Count

func (self *Conn) Count(key, min, max []byte, mininc, maxinc bool) (result int)

Count will count the number of keys between min and max in the sub tree defined by key.

func (*Conn) Del

func (self *Conn) Del(key []byte)

Del will remove the byte value under key.

func (*Conn) Describe

func (self *Conn) Describe() string

Describe will return a string representation of the known cluster of nodes.

func (*Conn) DescribeAllNodes

func (self *Conn) DescribeAllNodes() (result []common.DHashDescription)

DescribeAllNodes will return the description structures of all known nodes.

func (*Conn) DescribeAllTrees

func (self *Conn) DescribeAllTrees() string

DescribeAllTrees will return a string representation of the complete trees of all known nodes. Used for debug purposes, don't do it on big databases!

func (*Conn) DescribeNode

func (self *Conn) DescribeNode(pos []byte) (result common.DHashDescription, err error)

DescribeNode will return the description structure of the node at pos.

func (*Conn) DescribeTree

func (self *Conn) DescribeTree(pos []byte) (result string, err error)

DescribeTree will return a string representation of the complete tree in the node at pos. Used for debug purposes, don't do it on big databases!

func (*Conn) Dump

func (self *Conn) Dump() (c chan [2][]byte, wait *sync.WaitGroup)

Dump will return a channel to send multiple key/value pairs through. When finished, close the channel and #Wait for the *sync.WaitGroup.

func (*Conn) First

func (self *Conn) First(key []byte) (firstKey, firstValue []byte, existed bool)

First will return the first key and value in the sub tree defined by key.

func (*Conn) Get

func (self *Conn) Get(key []byte) (value []byte, existed bool)

Get will return the value under key.

func (*Conn) IndexOf

func (self *Conn) IndexOf(key, subKey []byte) (index int, existed bool)

IndexOf will return the the distance from the start for subKey, looking at the sub tree defined by key.

func (*Conn) Last

func (self *Conn) Last(key []byte) (lastKey, lastValue []byte, existed bool)

Last will return the last key and value in the sub tree defined by key.

func (*Conn) MirrorCount

func (self *Conn) MirrorCount(key, min, max []byte, mininc, maxinc bool) (result int)

MirrorCount will count the number of keys between min and max in the mirror tree of the sub tree defined by key.

func (*Conn) MirrorFirst

func (self *Conn) MirrorFirst(key []byte) (firstKey, firstValue []byte, existed bool)

MirrorFirst will return the first key and value in the mirror tree of the sub tree defined by key.

func (*Conn) MirrorIndexOf

func (self *Conn) MirrorIndexOf(key, subKey []byte) (index int, existed bool)

MirrorIndexOf will return the the distance from the start for subKey, looking at the mirror tree of the sub tree defined by key.

func (*Conn) MirrorLast

func (self *Conn) MirrorLast(key []byte) (lastKey, lastValue []byte, existed bool)

MirrorLast will return the last key and valuei in the mirror tree of the sub tree defined by key.

func (*Conn) MirrorNextIndex

func (self *Conn) MirrorNextIndex(key []byte, index int) (foundKey, foundValue []byte, foundIndex int, existed bool)

MirrorNextIndex will return the key, value and index of the first key after index in the mirror tree of the sub tree defined by key.

func (*Conn) MirrorPrevIndex

func (self *Conn) MirrorPrevIndex(key []byte, index int) (foundKey, foundValue []byte, foundIndex int, existed bool)

MirrorPrevIndex will return the key, value and index of the first key before index in the mirror tree of the sub tree defined by key.

func (*Conn) MirrorReverseIndexOf

func (self *Conn) MirrorReverseIndexOf(key, subKey []byte) (index int, existed bool)

MirrorReverseIndexOf will return the the distance from the end for subKey, looking at the mirror tree of the sub tree defined by key.

func (*Conn) MirrorReverseSlice

func (self *Conn) MirrorReverseSlice(key, min, max []byte, mininc, maxinc bool) (result []common.Item)

MirrorReverseSlice will return the reverse slice between min and max in the mirror tree of the sub tree defined by key. A min of nil will return from the end. A max of nil will return to the start.

func (*Conn) MirrorReverseSliceIndex

func (self *Conn) MirrorReverseSliceIndex(key []byte, min, max *int) (result []common.Item)

MirrorReverseSliceIndex will return the reverse slice between index min and max in the mirror tree of the sub tree defined by key. A min of nil will return from the end. A max of nil will return to the start.

func (*Conn) MirrorReverseSliceLen

func (self *Conn) MirrorReverseSliceLen(key, max []byte, maxinc bool, maxRes int) (result []common.Item)

MirrorReverseSliceLen will return at most maxRes elements before max in the mirror tree of the sub tree defined by key. A min of nil will return from the end.

func (*Conn) MirrorSlice

func (self *Conn) MirrorSlice(key, min, max []byte, mininc, maxinc bool) (result []common.Item)

MirrorSlice will return the slice between min and max in the mirror tree of the sub tree defined by key. A min of nil will return from the start. A max of nil will return to the end.

func (*Conn) MirrorSliceIndex

func (self *Conn) MirrorSliceIndex(key []byte, min, max *int) (result []common.Item)

MirrorSliceIndex will return the slice between index min and max in the mirror tree of the sub tree defined by key. A min of nil will return from the start. A max of nil will return to the end.

func (*Conn) MirrorSliceLen

func (self *Conn) MirrorSliceLen(key, min []byte, mininc bool, maxRes int) (result []common.Item)

MirrorSliceLen will return at most maxRes elements after min in the mirror tree of the sub tree defined by key. A min of nil will return from the start.

func (*Conn) Next

func (self *Conn) Next(key []byte) (nextKey, nextValue []byte, existed bool)

Next will return the next key and value after key.

func (*Conn) NextIndex

func (self *Conn) NextIndex(key []byte, index int) (foundKey, foundValue []byte, foundIndex int, existed bool)

NextIndex will return the key, value and index of the first key after index in the sub tree defined by key.

func (*Conn) Nodes

func (self *Conn) Nodes() common.Remotes

Nodes returns the set of known nodes for this Conn.

func (*Conn) Prev

func (self *Conn) Prev(key []byte) (prevKey, prevValue []byte, existed bool)

Prev will return the previous key and value before key.

func (*Conn) PrevIndex

func (self *Conn) PrevIndex(key []byte, index int) (foundKey, foundValue []byte, foundIndex int, existed bool)

PrevIndex will return the key, value and index of the first key before index in the sub tree defined by key.

func (*Conn) Put

func (self *Conn) Put(key, value []byte)

Put will put value under key.

func (*Conn) Reconnect

func (self *Conn) Reconnect()

Reconnect will try to refetch the set of known nodes from a randomly chosen currently known node.

func (*Conn) ReverseIndexOf

func (self *Conn) ReverseIndexOf(key, subKey []byte) (index int, existed bool)

ReverseIndexOf will return the the distance from the end for subKey, looking at the sub tree defined by key.

func (*Conn) ReverseSlice

func (self *Conn) ReverseSlice(key, min, max []byte, mininc, maxinc bool) (result []common.Item)

ReverseSlice will return the reverse slice between min and max in the sub tree defined by key. A min of nil will return from the end. A max of nil will return to the start.

func (*Conn) ReverseSliceIndex

func (self *Conn) ReverseSliceIndex(key []byte, min, max *int) (result []common.Item)

ReverseSliceIndex will the reverse slice between index min and max in the sub tree defined by key. A min of nil will return from the end. A max of nil will return to the start.

func (*Conn) ReverseSliceLen

func (self *Conn) ReverseSliceLen(key, max []byte, maxinc bool, maxRes int) (result []common.Item)

ReverseSliceLen will return at most maxRes elements before max in the sub tree defined by key. A min of nil will return from the end. A max of nil will return to the start.

func (*Conn) SDel

func (self *Conn) SDel(key []byte)

SDel will remove the byte value under key.

func (*Conn) SPut

func (self *Conn) SPut(key, value []byte)

SPut will put value under key.

func (*Conn) SSubClear

func (self *Conn) SSubClear(key []byte)

SSubClear will remove all byte values from the sub tree defined by key. It will retain delete markers for all deleted values.

func (*Conn) SSubDel

func (self *Conn) SSubDel(key, subKey []byte)

SSubDel will remove the value under subKey from the sub tree defined by key.

func (*Conn) SSubPut

func (self *Conn) SSubPut(key, subKey, value []byte)

SSubPut will put value under subKey in the sub tree defined by key.

func (*Conn) SetExpression

func (self *Conn) SetExpression(expr setop.SetExpression) (result []setop.SetOpResult)

SetExpression will execute the given expr.

If expr.Dest is set it will store the result under the sub tree defined by expr.Dest.

If expr.Dest is nil it will return the result.

Either expr.Op or expr.Code has to be set.

If expr.Op is nil expr.Code will be parsed using SetOpParser to provide expr.Op.

func (*Conn) Size

func (self *Conn) Size() (result int)

Size will return the total size of all known nodes.

func (*Conn) Slice

func (self *Conn) Slice(key, min, max []byte, mininc, maxinc bool) (result []common.Item)

Slice will return the slice between min and max in the sub tree defined by key. A min of nil will return from the start. A max of nil will return to the end.

func (*Conn) SliceIndex

func (self *Conn) SliceIndex(key []byte, min, max *int) (result []common.Item)

SliceIndex will return the slice between index min and max in the sub tree defined by key. A min of nil will return from the start. A max of nil will return to the end.

func (*Conn) SliceLen

func (self *Conn) SliceLen(key, min []byte, mininc bool, maxRes int) (result []common.Item)

SliceLen will return at most maxRes elements after min in the sub tree defined by key. A min of nil will return from the start.

func (*Conn) Start

func (self *Conn) Start()

Start will begin to regularly update the set of known nodes for this Conn.

func (*Conn) SubAddConfiguration

func (self *Conn) SubAddConfiguration(treeKey []byte, key, value string)

SubAddConfiguration will set a key and value to the configuration of the sub tree defined by key.

To mirror a sub tree, set mirrored=yes. To turn off mirroring of a sub tree, set mirrored!=yes.

func (*Conn) SubClear

func (self *Conn) SubClear(key []byte)

SubClear will remove all byte values from the sub tree defined by key. It will retain delete markers for all deleted values.

func (*Conn) SubConfiguration

func (self *Conn) SubConfiguration(key []byte) (conf map[string]string)

SubConfiguration will return the configuration for the sub tree defined by key.

mirrored=yes means that the sub tree is currently mirrored.

func (*Conn) SubDel

func (self *Conn) SubDel(key, subKey []byte)

SubDel will remove the value under subKey from the sub tree defined by key.

func (*Conn) SubDump

func (self *Conn) SubDump(key []byte) (c chan [2][]byte, wait *sync.WaitGroup)

SubDump will return a channel to send multiple key/value pairs to a given sub tree through. When finished, close the channel and #Wait for the *sync.WaitGroup.

func (*Conn) SubGet

func (self *Conn) SubGet(key, subKey []byte) (value []byte, existed bool)

SubGet will return the value under subKey in the sub tree defined by key.

func (*Conn) SubMirrorNext

func (self *Conn) SubMirrorNext(key, subKey []byte) (nextKey, nextValue []byte, existed bool)

SubMirrorNext will return the next key and value after subKey in the sub tree defined by key.

func (*Conn) SubMirrorPrev

func (self *Conn) SubMirrorPrev(key, subKey []byte) (prevKey, prevValue []byte, existed bool)

SubMirrorPrev will return the previous key and value before subKey in the sub tree defined by key.

func (*Conn) SubNext

func (self *Conn) SubNext(key, subKey []byte) (nextKey, nextValue []byte, existed bool)

SubNext will return the next key and value after subKey in the sub tree defined by key.

func (*Conn) SubPrev

func (self *Conn) SubPrev(key, subKey []byte) (prevKey, prevValue []byte, existed bool)

SubPrev will return the previous key and value before subKey in the sub tree defined by key.

func (*Conn) SubPut

func (self *Conn) SubPut(key, subKey, value []byte)

SubPut will put value under subKey in the sub tree defined by key.

func (*Conn) SubSize

func (self *Conn) SubSize(key []byte) (result int)

SubSize will return the size of the sub tree defined by key.