mcache

package module
v1.0.1 Latest Latest
Warning

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

Go to latest
Published: Mar 23, 2023 License: MIT Imports: 2 Imported by: 0

README

go-mcache

.github/workflows/ci.yaml Coverage Status Go Report Card Reference

Yet another in-memory cache library with expiration.

Uses generics and does not use periodic check for expired items. Instead, it uses internal ordered queue to range items in order of expiration and just sleeps until it is time to expire an item. thus having minimal computational overhead.

Installation

go get github.com/dmytro-vovk/go-mcache

Usage

// Create a new instance with string keys and int values
c := mcache.New[string, int]()

// Set couple values
c.Set("one", 1, time.Minute)
c.Set("two", 2, time.Hour)

// Get a value
if value, ok := c.Get("one"); ok {
	fmt.Printf("Got value: %v", value)
}

// Get value and delete it from the cache
if value, ok := GetAndDelete("two"); ok {
    fmt.Printf("Got and deleted value: %v", value)
}

// Try getting non-existing value
if _, ok := Get("two"); !ok {
    fmt.Print("Value no longer cached")
}

// Set different value for the key keeping the same TTL
if c.Update("one", 101) {
    fmt.Print("Value was updated")
}

// Replace the value getting the previous one
if value, ok := c.Swap("one", 202); ok {
    fmt.Printf("Previous value was %v", value)
}

// Delete a value
if c.Delete("one") {
    fmt.Print("The value is deleted")
}

// Change the value TTL 
if c.Refresh("one", time.Hour) {
    fmt.Print("TTL for the key is set to one hour")
}

// Let's see how many values we have
fmt.Printf("We have %d values", c.Len())

// Let's free some memory by evicting some data
if evicted := c.Evict(10); evicted > 0 {
    fmt.Printf("Evicted %d values", evicted)
}

// Value expires
c.Set("gone fast", 1000, time.Millisecond)
time.Sleep(time.Millisecond)
if _, ok := c.Get("gone fast"); !ok {
    fmt.Print("the value is gone!")
}

Benchmarks

goos: darwin
goarch: amd64
pkg: github.com/dmytro-vovk/go-mcache
cpu: Intel(R) Core(TM) i9-8950HK CPU @ 2.90GHz
BenchmarkCacheSet
BenchmarkCacheSet-12       	 2389052	       485.8 ns/op	     243 B/op	       2 allocs/op
BenchmarkCacheGet
BenchmarkCacheGet-12       	72900222	        15.56 ns/op	       2 B/op	       0 allocs/op
BenchmarkCacheAddGet
BenchmarkCacheAddGet-12    	  781284	      1662 ns/op	     607 B/op	      10 allocs/op

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Cache

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

func New

func New[K comparable, V any]() *Cache[K, V]

New creates a news cache instance, using any comparable type for keys, and any type for values.

func (*Cache[K, V]) Delete

func (c *Cache[K, V]) Delete(key K) (ok bool)

Delete removes value from thr cache.

func (*Cache[K, V]) Evict

func (c *Cache[K, V]) Evict(n int) (evicted int)

Evict removes (at most) n items that expire earliest, returning the number of actually evicted items.

func (*Cache[K, V]) Get

func (c *Cache[K, V]) Get(key K) (V, bool)

Get returns value and true, if key exists, of zero value and false if not found.

func (*Cache[K, V]) GetAndDelete

func (c *Cache[K, V]) GetAndDelete(key K) (V, bool)

GetAndDelete returns value and true, and deletes the key if it was found, of zero value and false if the key not found.

func (*Cache[K, V]) GetMany added in v0.0.3

func (c *Cache[K, V]) GetMany(keys ...K) map[K]V

GetMany returns key/value pairs as a map. Will not return non-existing keys/expired values.

func (*Cache[K, V]) Len

func (c *Cache[K, V]) Len() int

Len returns number of items currently stored in the cache.

func (*Cache[K, V]) Range added in v0.0.2

func (c *Cache[K, V]) Range(fn func(K, V) bool)

Range iterates over key/value pairs using supplied function until it returns false. Values are provided in the order of eviction. It is safe to manipulate the cache within the function.

func (*Cache[K, V]) Refresh

func (c *Cache[K, V]) Refresh(key K, ttl time.Duration) bool

Refresh sets new TTL for the given key, returning true if the key (still) exists.

func (*Cache[K, V]) Rekey added in v0.0.3

func (c *Cache[K, V]) Rekey(oldKey, newKey K) bool

Rekey replaces value's key. Returns false if the old key is not present.

func (*Cache[K, V]) Set

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

Set adds or replaces a value with key and given TTL.

func (*Cache[K, V]) Swap

func (c *Cache[K, V]) Swap(key K, value V) (V, bool)

Swap sets the new value returning the old one. Will return false if key is not found.

func (*Cache[K, V]) Update

func (c *Cache[K, V]) Update(key K, value V) bool

Update sets new value for key without changing TTL, returning false if key not found.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL