sled

README

Sled

Sled is a high performance Key/Value store based on a ctrie data structure. Sled is non-blocking and thread safe, meaning it is safe to access from any number of threads simultaneously.

Any type of data can be stored in a key, but sled maintains the benefits of the Go type system by enforcing the type. Values must be accessed by passing an empty type value of the same type into the Get method.

Usage

go get "github.com/Avalanche-io/sled"

Create a sled with sled.New().

sl := sled.New()

Setting a key. Sled accepts any type.

sl.Set("key", "value")
sl.Set("Answer to the Ultimate Question", 42)
sl.Set("primes", []int{2, 3, 5, 7, 11, 13, 17, 19, 23, 29})

Getting a value.

var primes []int
var ultimate_answer int
var right_value_type string
var wrong_value_type []byte

err := sl.Get("Answer to the Ultimate Question", &ultimate_answer)
fmt.Printf("Answer to the Ultimate Question: %d, err: %t\n", ultimate_answer, err != nil)
err = sl.Get("primes", &primes)
fmt.Printf("Primes: %v, err: %t\n", primes, err != nil)
err = sl.Get("key", &wrong_value_type)
fmt.Printf("key: %v, err: %t\n", right_value_type, err != nil)
fmt.Printf("key (wrong type): %v, err: %s\n", wrong_value_type, err)
err = sl.Get("key", &right_value_type)

Setting a key conditionally. SetIfNil will only assign the value if the key is not already set.

SetIfNil(string, interface{}) bool

Deleting a key.

Delete(string) (interface{}, bool)

Close, when done with a sled close it, to free resources.

Close() error

Iterating over all keys, can be done with range expression.

stop := chan struct{} // or nil if interruption isn't needed.
for elm := range sl.Iterate(stop) {
    fmt.Printf("key: %s  value: %v\n", elm.Key(), elm.Value())
    elm.Close() // close the Element when done 
}

A Snapshot is a nearly zero cost copy of a sled that will not be effected by future changes to the source sled. It can be made mutable or immutable by setting the argument to sled.ReadWrite, or sled.ReadOnly.

sl_mutable := sl.Snapshot(sled.ReadWrite)
sl_immutable := sl.Snapshot(sled.ReadOnly)

Example

package main

import (
    "fmt"

    "github.com/Avalanche-io/sled"
)

func main() {
    sl := sled.New()

    key := "The meaning of life"
    sl.Set(key, 42)
    
    var v int
    err := sl.Get(key, &v)
    if err != nil {
        panic(err)
    }
    fmt.Printf("key: %s, \tvalue: %v\n", key, v)
}

Documentation

Overview

Package sled implements a non-blocking, thread safe key value store. When used in multiple threads Sled is faster than go's built in map type which must be combined with synchronization primitives.

Index

• Variables
• type Element
• type ErrCanceled
  • func (ErrCanceled) Error() string
• type ErrGetType
  • func (e ErrGetType) Error() string
• type IoMode
• type Sled
  • func New() Sled

Variables

var (

	// ErrEmptyList is returned when an invalid operation is performed on an
	// empty list.
	ErrEmptyList = errors.New("Empty list")
)

Types

type Element

type Element interface {
	Key() string
	Value() interface{}
	Close()
}

Element is interface for accessing keys and values when iterating. For effectuate memory utilization elements are implemented as a pool of re-usable structures and therefore must be closed after use.

type ErrCanceled

type ErrCanceled struct{}

func (ErrCanceled) Error

func (ErrCanceled) Error() string

type ErrGetType

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

func (ErrGetType) Error

func (e ErrGetType) Error() string

type IoMode

type IoMode uint

IoMode represents the mode of a sled as either ReadWrite, or ReadOnly.

const (
	ReadOnly IoMode = iota
	ReadWrite
)

type Sled

type Sled interface {
	Set(key string, v interface{}) error
	Get(key string, v interface{}) error
	SetIfNil(string, interface{}) bool
	Delete(string) (interface{}, bool)
	Close() error
	Iterate(<-chan struct{}) <-chan Element
	Snapshot(IoMode) Sled
	Size() uint
}

Sled is an interface for sled key value store types.

func New

func New() Sled

Create a new Sled object.