mattmemory

README

Matt Memory ⚡

matt-memory is a customizable and scalable distributed cache package for Go, providing rapid data access that can be tailored to meet specific application requirements.

Flexibility

Users have granular control over key parameters of the cache, so that they can customize the cache's behaviour according to specific needs:

1. idealItemsPerShard: By specifying the ideal number of items per shard, users can customize the cache to achieve their optimal balance between fast data access and efficient memory usage.

2. loadBalancingInterval: Users can customize the time interval that the cache performs automatic load balancing, giving them the option to optimize workload distribution based on their specific needs.

Features

🧩 Consistent Hashing: Distributes data across shards using FNV-1a hashing, supporting a balanced distribution across horizontal partitions, while enabling fast cache data retrieval and storage.

📊 Automatic Load Balancing: Redistributes load automatically across shards, optimizing resource usage and ensuring consistent data access speeds.

⌛ TTL Support: Enables the storage of key-value pairs with Time-to-Live (TTL) expirations, allowing for the efficient management of cache memory and ensuring that outdated data is automatically evicted.

🔐 Concurrent Safe: Ensures safe operations in concurrent access scenarios with mutex locks, guaranteeing thread safety by allowing multiple concurrent reads while enforcing exclusive access during writes.

Usage

matt-memory can be installed in your Go project as follows:

go get github.com/mat-ng/matt-memory

Provided below is an example of how to use the cache:

package main

import (
	"fmt"
	"time"

	mattmemory "github.com/mat-ng/matt-memory"
)

func main() {
	// Define the cache parameters
	idealItemsPerShard := 10
	loadBalancingInterval := time.Hour

	// Create a new cache instance
	cache, err := mattmemory.New(idealItemsPerShard, loadBalancingInterval)
	if err != nil {
		fmt.Printf("Error creating cache: %v\n", err)
		return
	}

	// Set a key-value pair in the cache with a TTL of 30 seconds
	key := []byte("key1")
	value := []byte("value1")
	err = cache.Set(key, value, 30*time.Second)
	if err != nil {
		fmt.Println("error setting value:", err)
		return
	}

	// Get the value from the cache
	result, err := cache.Get(key)
	if err != nil {
		fmt.Println("error getting value:", err)
		return
	} else {
		fmt.Println("value retrieved:", string(result))
	}

	// Check if the key exists in the cache
	if cache.Has(key) {
		fmt.Println("key exists in the cache")
	} else {
		fmt.Println("key does not exist in the cache")
	}

	// Delete the key from the cache
	err = cache.Delete(key)
	if err != nil {
		fmt.Println("error deleting key:", err)
		return
	} else {
		fmt.Println("key deleted successfully")
	}
}

License

MIT License

Documentation

Index

• type Cache
  • func New(idealItemsPerShard int, loadBalancingInterval time.Duration) (*Cache, error)
  • func (c *Cache) Delete(key []byte) error
  • func (c *Cache) Get(key []byte) ([]byte, error)
  • func (c *Cache) Has(key []byte) bool
  • func (c *Cache) Set(key []byte, value []byte, ttl time.Duration) error
• type Cacher

Types

type Cache

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

func New

func New(idealItemsPerShard int, loadBalancingInterval time.Duration) (*Cache, error)

func (*Cache) Delete

func (c *Cache) Delete(key []byte) error

func (*Cache) Get

func (c *Cache) Get(key []byte) ([]byte, error)

func (*Cache) Has

func (c *Cache) Has(key []byte) bool

func (*Cache) Set

func (c *Cache) Set(key []byte, value []byte, ttl time.Duration) error

type Cacher

type Cacher interface {
	// Retrieves the value associated with a given key from the distributed cache.
	// Returns the value as a byte slice. If they key does not exist, returns an error.
	Get([]byte) ([]byte, error)

	// Stores a value in the cache with the specified key and optional time-to-live (TTL).
	// If the TTL is zero, the key-value pair is held indefinitely.
	// Returns an error if the operation fails.
	Set([]byte, []byte, time.Duration) error

	// Removes the key-value pair of the given key from the distributed cache.
	// If the key does not exist, returns an error.
	Delete([]byte) error

	// Checks if the distributed cache contains a value associated with the given key.
	// If the key-value pair exists in the cache, returns true. Otherwise, returns false.
	Has([]byte) bool
}