dmap

Documentation

Index

• Constants
• Variables
• func NewService(e *environment.Environment) (service.Service, error)
• type Cursor
  • func (c *Cursor) Close()
  • func (c *Cursor) Range(f func(key string, value interface{}) bool) error
• type DMap
  • func (dm *DMap) Decr(key string, delta int) (int, error)
  • func (dm *DMap) Delete(key string) error
  • func (dm *DMap) Destroy() error
  • func (dm *DMap) Expire(key string, timeout time.Duration) error
  • func (dm *DMap) Get(key string) (interface{}, error)
  • func (dm *DMap) GetEntry(key string) (*Entry, error)
  • func (dm *DMap) GetPut(key string, value interface{}) (interface{}, error)
  • func (dm *DMap) Incr(key string, delta int) (int, error)
  • func (dm *DMap) Lock(key string, deadline time.Duration) (*LockContext, error)
  • func (dm *DMap) LockWithTimeout(key string, timeout, deadline time.Duration) (*LockContext, error)
  • func (dm *DMap) Name() string
  • func (dm *DMap) Put(key string, value interface{}) error
  • func (dm *DMap) PutEx(key string, value interface{}, timeout time.Duration) error
  • func (dm *DMap) PutIf(key string, value interface{}, flags int16) error
  • func (dm *DMap) PutIfEx(key string, value interface{}, timeout time.Duration, flags int16) error
  • func (dm *DMap) Query(q query.M) (*Cursor, error)
• type Entry
• type LockContext
  • func (l *LockContext) Unlock() error
• type QueryResponse
• type Service
  • func (s *Service) NewDMap(name string) (*DMap, error)
  • func (s *Service) RegisterOperations(operations map[protocol.OpCode]func(w, r protocol.EncodeDecoder))
  • func (s *Service) Shutdown(ctx context.Context) error
  • func (s *Service) Start() error

Constants

const (
	IfNotFound = int16(1) << iota
	IfFound
)

const NumConcurrentWorkers = 2

NumConcurrentWorkers is the number of concurrent workers to run a query on the cluster.

Variables

var (
	// DeleteHits is the number of deletion reqs resulting in an item being removed.
	DeleteHits = stats.NewInt64Counter()

	// DeleteMisses is the number of deletions reqs for missing keys
	DeleteMisses = stats.NewInt64Counter()
)

var (
	// ErrKeyNotFound is returned when a key could not be found.
	ErrKeyNotFound  = neterrors.New(protocol.StatusErrKeyNotFound, "key not found")
	ErrDMapNotFound = errors.New("dmap not found")
	ErrServerGone   = errors.New("server is gone")
)

var (
	// GetMisses is the number of entries that have been requested and not found
	GetMisses = stats.NewInt64Counter()

	// GetHits is the number of entries that have been requested and found present
	GetHits = stats.NewInt64Counter()

	// EvictedTotal is the number of entries removed from cache to free memory for new entries.
	EvictedTotal = stats.NewInt64Counter()
)

var (
	// ErrLockNotAcquired is returned when the requested lock could not be acquired
	ErrLockNotAcquired = neterrors.New(protocol.StatusErrLockNotAcquired, "lock not acquired")

	// ErrNoSuchLock is returned when the requested lock does not exist
	ErrNoSuchLock = neterrors.New(protocol.StatusErrNoSuchLock, "no such lock")
)

var (
	ErrKeyFound    = neterrors.New(protocol.StatusErrKeyFound, "key found")
	ErrWriteQuorum = neterrors.New(protocol.StatusErrWriteQuorum, "write quorum cannot be reached")
	ErrKeyTooLarge = neterrors.New(protocol.StatusErrKeyTooLarge, "key too large")
)

var EntriesTotal = stats.NewInt64Counter()

EntriesTotal is the total number of entries(including replicas) stored during the life of this instance.

var ErrEndOfQuery = neterrors.New(protocol.StatusErrEndOfQuery, "end of query")

ErrEndOfQuery is the error returned by Range when no more data is available. Functions should return ErrEndOfQuery only to signal a graceful end of input.

var ErrReadQuorum = neterrors.New(protocol.StatusErrReadQuorum, "read quorum cannot be reached")

Functions

func NewService

func NewService(e *environment.Environment) (service.Service, error)

Types

type Cursor

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

Cursor implements distributed query on DMaps.

func (*Cursor) Close

func (c *Cursor) Close()

Close cancels the underlying context and background goroutines stops running.

func (*Cursor) Range

func (c *Cursor) Range(f func(key string, value interface{}) bool) error

Range calls f sequentially for each key and value yielded from the cursor. If f returns false, range stops the iteration.

type DMap

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

DMap implements a single-hop distributed hash table.

func (*DMap) Decr

func (dm *DMap) Decr(key string, delta int) (int, error)

Decr atomically decrements key by delta. The return value is the new value after being decremented or an error.

func (*DMap) Delete

func (dm *DMap) Delete(key string) error

Delete deletes the value for the given key. Delete will not return error if key doesn't exist. It's thread-safe. It is safe to modify the contents of the argument after Delete returns.

func (*DMap) Destroy

func (dm *DMap) Destroy() error

Destroy flushes the given DMap on the cluster. You should know that there is no global lock on DMaps. So if you call Put, PutEx and Destroy methods concurrently on the cluster, Put and PutEx calls may set new values to the DMap.

func (*DMap) Expire

func (dm *DMap) Expire(key string, timeout time.Duration) error

Expire updates the expiry for the given key. It returns ErrKeyNotFound if the DB does not contains the key. It's thread-safe.

func (*DMap) Get

func (dm *DMap) Get(key string) (interface{}, error)

Get gets the value for the given key. It returns ErrKeyNotFound if the DB does not contains the key. It's thread-safe. It is safe to modify the contents of the returned value.

func (*DMap) GetEntry

func (dm *DMap) GetEntry(key string) (*Entry, error)

GetEntry gets the value for the given key with its metadata. It returns ErrKeyNotFound if the DB does not contains the key. It's thread-safe. It is safe to modify the contents of the returned value.

func (*DMap) GetPut

func (dm *DMap) GetPut(key string, value interface{}) (interface{}, error)

GetPut atomically sets key to value and returns the old value stored at key.

func (*DMap) Incr

func (dm *DMap) Incr(key string, delta int) (int, error)

Incr atomically increments key by delta. The return value is the new value after being incremented or an error.

func (*DMap) Lock

func (dm *DMap) Lock(key string, deadline time.Duration) (*LockContext, error)

Lock sets a lock for the given key. Acquired lock is only for the key in this dmap.

It returns immediately if it acquires the lock for the given key. Otherwise, it waits until deadline.

You should know that the locks are approximate, and only to be used for non-critical purposes.

func (*DMap) LockWithTimeout

func (dm *DMap) LockWithTimeout(key string, timeout, deadline time.Duration) (*LockContext, error)

LockWithTimeout sets a lock for the given key. If the lock is still unreleased the end of given period of time, it automatically releases the lock. Acquired lock is only for the key in this dmap.

It returns immediately if it acquires the lock for the given key. Otherwise, it waits until deadline.

You should know that the locks are approximate, and only to be used for non-critical purposes.

func (*DMap) Name

func (dm *DMap) Name() string

Name exposes name of the DMap.

func (*DMap) Put

func (dm *DMap) Put(key string, value interface{}) error

Put sets the value for the given key. It overwrites any previous value for that key and it's thread-safe. The key has to be string. value type is arbitrary. It is safe to modify the contents of the arguments after Put returns but not before.

func (*DMap) PutEx

func (dm *DMap) PutEx(key string, value interface{}, timeout time.Duration) error

PutEx sets the value for the given key with TTL. It overwrites any previous value for that key. It's thread-safe. The key has to be string. value type is arbitrary. It is safe to modify the contents of the arguments after Put returns but not before.

func (*DMap) PutIf

func (dm *DMap) PutIf(key string, value interface{}, flags int16) error

PutIf Put sets the value for the given key. It overwrites any previous value for that key and it's thread-safe. The key has to be string. value type is arbitrary. It is safe to modify the contents of the arguments after Put returns but not before. Flag argument currently has two different options:

IfNotFound: Only set the key if it does not already exist. It returns ErrFound if the key already exist.

IfFound: Only set the key if it already exist. It returns ErrKeyNotFound if the key does not exist.

func (*DMap) PutIfEx

func (dm *DMap) PutIfEx(key string, value interface{}, timeout time.Duration, flags int16) error

PutIfEx sets the value for the given key with TTL. It overwrites any previous value for that key. It's thread-safe. The key has to be string. value type is arbitrary. It is safe to modify the contents of the arguments after Put returns but not before. Flag argument currently has two different options:

IfNotFound: Only set the key if it does not already exist. It returns ErrFound if the key already exist.

IfFound: Only set the key if it already exist. It returns ErrKeyNotFound if the key does not exist.

func (*DMap) Query

func (dm *DMap) Query(q query.M) (*Cursor, error)

Query runs a distributed query on a dmap instance. Olric supports a very simple query DSL and now, it only scans keys. The query DSL has very few keywords:

$onKey: Runs the given query on keys or manages options on keys for a given query.

$onValue: Runs the given query on values or manages options on values for a given query.

$options: Useful to modify data returned from a query

Keywords for $options:

$ignore: Ignores a value.

A distributed query looks like the following:

  query.M{
	  "$onKey": query.M{
		  "$regexMatch": "^even:",
		  "$options": query.M{
			  "$onValue": query.M{
				  "$ignore": true,
			  },
		  },
	  },
  }

This query finds the keys starts with "even:", drops the values and returns only keys. If you also want to retrieve the values, just remove the $options directive:

  query.M{
	  "$onKey": query.M{
		  "$regexMatch": "^even:",
	  },
  }

In order to iterate over all the keys:

  query.M{
	  "$onKey": query.M{
		  "$regexMatch": "",
	  },
  }

Query function returns a cursor which has Range and Close methods. Please take look at the Range function for further info.

type Entry

type Entry struct {
	Key       string
	Value     interface{}
	TTL       int64
	Timestamp int64
}

Entry is a DMap entry with its metadata.

type LockContext

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

LockContext is returned by Lock and LockWithTimeout methods. It should be stored in a proper way to release the lock.

func (*LockContext) Unlock

func (l *LockContext) Unlock() error

Unlock releases the lock.

type QueryResponse

type QueryResponse map[string]interface{}

QueryResponse denotes returned data by a node for query.

type Service

type Service struct {
	sync.RWMutex // protects dmaps map
	// contains filtered or unexported fields
}

func (*Service) NewDMap

func (s *Service) NewDMap(name string) (*DMap, error)

NewDMap creates and returns a new DMap instance. It checks member count quorum and bootstrapping status before creating a new DMap.

func (*Service) RegisterOperations

func (s *Service) RegisterOperations(operations map[protocol.OpCode]func(w, r protocol.EncodeDecoder))

func (*Service) Shutdown

func (s *Service) Shutdown(ctx context.Context) error

func (*Service) Start

func (s *Service) Start() error

Start starts the distributed map service.