persist

package module
v0.0.0-...-4ad3dbc Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 28, 2024 License: ISC Imports: 7 Imported by: 1

README

Package persist provides a basic type-safe map that persists to disk.

Documentation

See Go Documentation.

Documentation

Overview

Package persist provides a basic type-safe map that persists to disk.

Example (Map) 
package main

import (
	"fmt"
	"log"

	"libdb.so/persist"
	"libdb.so/persist/driver/badgerdb"
)

func main() {
	type User struct {
		ID   int
		Name string
	}

	m, err := persist.NewMustMap[string, User](badgerdb.Open, ":memory:")
	if err != nil {
		log.Fatalln("cannot create badgerdb-backed map:", err)
	}
	defer m.Close()

	m.Store("foo", User{ID: 1, Name: "foo"})
	m.Store("bar", User{ID: 2, Name: "bar"})

	u, ok := m.Load("foo")
	fmt.Println(u, ok)

	iter := m.All()
	iter(func(k string, u User) bool {
		fmt.Printf("%s: %v\n", k, u)
		return true
	})

}

Output:

{1 foo} true
bar: {2 bar}
foo: {1 foo}
Example (Value) 
package main

import (
	"fmt"
	"log"

	"libdb.so/persist"
	"libdb.so/persist/driver/badgerdb"
)

func main() {
	type Config struct {
		EnableBananas bool
	}

	c, err := persist.NewMustValue[Config](badgerdb.Open, ":memory:")
	if err != nil {
		log.Fatalln("cannot create badgerdb-backed map:", err)
	}
	defer c.Close()

	c.Store(Config{EnableBananas: true})

	u, _ := c.Load()
	fmt.Printf("%+v\n", u)

}

Output:

{EnableBananas:true}

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Driver 

type Driver interface {
	io.Closer
	AcquireRO(func(DriverReadOnlyTx) error) error
	AcquireRW(func(DriverReadWriteTx) error) error
}

Driver is a driver for a persistent map. It exposes the ability to acquire read-only and read-write transactions. Note that transactions are assumed to have the properties of a database transaction, i.e. they are atomic and isolated.

type DriverOpenFunc 

type DriverOpenFunc func(path string) (Driver, error)

DriverOpenFunc is a function that opens a driver. It assumes that drivers already have a sane default configuration, so the user is not provided with any configuration options.

There is one exception: if the path exactly matches the string ":memory:", then the driver must be non-persistent. If the driver is unable to satisfy this requirement, it must return an error. 

var CBORDriver DriverOpenFunc = openCBORDriver

CBORDriver is a driver that stores data in a CBOR file. 

var DefaultDriver DriverOpenFunc = CBORDriver

DefaultDriver is the default driver. Nothing uses it, but it's here for convenience.

type DriverReadOnlyTx 

type DriverReadOnlyTx interface {
	Get(k []byte) ([]byte, bool, error)
	Each(func(k, v []byte) error) error
	EachKey(func(k []byte) error) error
}

DriverReadOnlyTx is a read-only transaction.

type DriverReadWriteTx 

type DriverReadWriteTx interface {
	DriverReadOnlyTx
	Set(k, v []byte) error
	Delete(k []byte) error
}

DriverReadWriteTx is a read-write transaction.

type Encoder 

type Encoder[T any] interface {
	// Encode encodes a value to a byte slice.
	// A byte slice is passed to allow reusing the same slice
	// for multiple encodings.
	Encode(T, []byte) ([]byte, error)
	// Decode decodes a value from a byte slice. The byte slice
	// must not be modified or stored.
	Decode([]byte) (T, error)
}

Encoder is a type that can encode a value to a byte slice. Such value must also be decodable from the same byte slice.

func BytesEncoder 

func BytesEncoder[T []byte]() Encoder[T]

BytesEncoder returns an Encoder that encodes values literally as byte slices. Use this for fast key formatting.

func CBOREncoder 

func CBOREncoder[T any]() Encoder[T]

CBOREncoder returns an Encoder that encodes values using the CBOR format.

func StringEncoder 

func StringEncoder[T ~string]() Encoder[T]

StringEncoder returns an Encoder that encodes values literally as strings. Use this for fast key formatting.

func StringerEncoder 

func StringerEncoder[T fmt.Stringer](parser func(s string) (T, error)) Encoder[T]

StringerEncoder returns an Encoder that encodes values using the Stringer interface. A parser function must be provided to decode the value from the string representation.

type EncoderPair 

type EncoderPair[K, V any] struct {
	Key   Encoder[K]
	Value Encoder[V]
}

EncoderPair is a pair of encoders.

type Map 

type Map[K, V any] struct {
	// contains filtered or unexported fields
}

Map is a type-safe map that persists to disk.

func NewMap 

func NewMap[K, V any](driverOpener DriverOpenFunc, path string) (Map[K, V], error)

NewMap returns a new Map using the default CBOR encoder and a provided driver with sane defaults.

func NewMapFromEncoders 

func NewMapFromEncoders[K, V any](driver Driver, encs EncoderPair[K, V]) *Map[K, V]

NewMapFromEncoders returns a new Map from a pair of encoders.

func (Map[K, V]) All 

func (m Map[K, V]) All() Seq2[K, V]

All returns an iterator over all key-value pairs in the map.

func (Map[K, V]) Close 

func (m Map[K, V]) Close() error

Close closes the map. The user must call this function to ensure that the map is properly closed.

func (Map[K, V]) Delete 

func (m Map[K, V]) Delete(k K) error

Delete deletes a key-value pair.

func (Map[K, V]) Encoder 

func (m Map[K, V]) Encoder() EncoderPair[K, V]

Encoder returns the encoder pair used by the map.

func (Map[K, V]) Keys 

func (m Map[K, V]) Keys() Seq[K]

Keys returns an iterator over all keys in the map.

func (Map[K, V]) Load 

func (m Map[K, V]) Load(k K) (V, bool, error)

Load gets a value by key.

func (Map[K, V]) LoadAndDelete 

func (m Map[K, V]) LoadAndDelete(k K) (v V, loaded bool, err error)

LoadAndDelete gets a value by key, or deletes the key if it is not found.

func (Map[K, V]) LoadOrStore 

func (m Map[K, V]) LoadOrStore(k K, v V) (value V, loaded bool, err error)

LoadOrStore gets a value by key, or stores a value if the key is not found.

func (Map[K, V]) Store 

func (m Map[K, V]) Store(k K, v V) error

Store sets a key-value pair.

type MustMap 

type MustMap[K, V any] struct {
	Map[K, V]
}

MustMap wraps a map and guarantees that no errors will be returned from the map's methods, with the exception of Get, which now returns a bool.

func NewMustMap 

func NewMustMap[K, V any](driverOpener DriverOpenFunc, path string) (MustMap[K, V], error)

NewMustMap returns a new MustMap. It has the same exact signature as NewMap, and the user must still handle errors as they would with NewMap.

func WrapMustMap 

func WrapMustMap[K, V any](m Map[K, V]) MustMap[K, V]

WrapMustMap wraps a Map in a MustMap.

func (MustMap[K, V]) Delete 

func (m MustMap[K, V]) Delete(key K)

Delete deletes the key-value pair. If an error occurs, the function panics.

func (MustMap[K, V]) Load 

func (m MustMap[K, V]) Load(key K) (V, bool)

Load returns the value associated with the key, or false if the key is not found.

func (MustMap[K, V]) LoadAndDelete 

func (m MustMap[K, V]) LoadAndDelete(key K) (value V, loaded bool)

LoadAndDelete returns the value associated with the key, or false if the key is not found. If an error occurs, the function panics.

func (MustMap[K, V]) LoadOrStore 

func (m MustMap[K, V]) LoadOrStore(key K, value V) (actual V, loaded bool)

LoadOrStore returns the existing value associated with the key if one exists, or stores and returns the given value. If an error occurs, the function panics.

func (MustMap[K, V]) Store 

func (m MustMap[K, V]) Store(key K, value V)

Store sets the value associated with the key. If an error occurs, the function panics.

type MustValue 

type MustValue[V any] struct {
	Value[V]
}

MustValue wraps a value and guarantees that no errors will be returned from the value's methods.

func NewMustValue 

func NewMustValue[V any](driverOpener DriverOpenFunc, path string) (MustValue[V], error)

NewMustValue returns a new MustValue. It has the same exact signature as NewValue, and the user must still handle errors as they would with NewValue.

func NewMustValueWithDefault 

func NewMustValueWithDefault[V any](driverOpener DriverOpenFunc, path string, def V) (MustValue[V], error)

NewMustValueWithDefault returns a new MustValue. It has the same exact signature as NewValueWithDefault, and the user must still handle errors as they would with NewValueWithDefault.

func WrapMustValue 

func WrapMustValue[V any](value Value[V]) MustValue[V]

WrapMustValue wraps a Value in a MustValue.

func (MustValue[V]) Delete 

func (m MustValue[V]) Delete()

func (MustValue[V]) Load 

func (m MustValue[V]) Load() (V, bool)

func (MustValue[V]) LoadAndDelete 

func (m MustValue[V]) LoadAndDelete() (V, bool)

func (MustValue[V]) LoadOrStore 

func (m MustValue[V]) LoadOrStore(value V) (actual V, loaded bool)

func (MustValue[V]) Store 

func (m MustValue[V]) Store(value V)

type Seq 

type Seq[V any] func(yield func(V) bool)

Seq is an iterator over a map that yields values. It is inspired by https://github.com/golang/go/issues/61897.

type Seq2 

type Seq2[K, V any] func(yield func(K, V) bool)

Seq2 is an iterator over a map that yields key-value pairs. It is inspired by https://github.com/golang/go/issues/61897.

type Value 

type Value[V any] interface {
	// Store sets the value.
	Store(value V) error
	// Load gets the value.
	Load() (V, bool, error)
	// LoadOrStore gets the value, or stores the value if it doesn't exist.
	LoadOrStore(value V) (actual V, loaded bool, err error)
	// LoadAndDelete gets the value and deletes it.
	LoadAndDelete() (V, bool, error)
	// Delete deletes the value.
	Delete() error
	// Close closes the value.
	Close() error
}

Value is a type-safe value that persists to disk.

func NewMappedValue 

func NewMappedValue[K, V any](m Map[K, V], key K) Value[V]

NewMappedValue returns a new Value using the provided map and key.

func NewValue 

func NewValue[V any](driverOpener DriverOpenFunc, path string) (Value[V], error)

NewValue returns a new Value using the default CBOR encoder and a provided driver with sane defaults.

func NewValueWithDefault 

func NewValueWithDefault[V any](driverOpener DriverOpenFunc, path string, def V) (Value[V], error)

NewValueWithDefault returns a new Value using the default CBOR encoder and the provided driver with sane defaults. If the value doesn't exist, it will be set to the provided default.

Source Files

View all Source files

Directories

Path Synopsis
driver
badgerdb

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.