Merge 05cdbdb6c1 into 46f4078530

README.md

@@ -45,34 +45,10 @@ func main() {
 		fmt.Println(foo)
 	}
 
-	// Since Go is statically typed, and cache values can be anything, type
-	// assertion is needed when values are being passed to functions that don't
-	// take arbitrary types, (i.e. interface{}). The simplest way to do this for
-	// values which will only be used once--e.g. for passing to another
-	// function--is:
-	foo, found := c.Get("foo")
-	if found {
-		MyFunction(foo.(string))
-	}
-
-	// This gets tedious if the value is used several times in the same function.
-	// You might do either of the following instead:
-	if x, found := c.Get("foo"); found {
-		foo := x.(string)
-		// ...
-	}
-	// or
-	var foo string
-	if x, found := c.Get("foo"); found {
-		foo = x.(string)
-	}
-	// ...
-	// foo can then be passed around freely as a string
-
 	// Want performance? Store pointers!
 	c.Set("foo", &MyStruct, cache.DefaultExpiration)
 	if x, found := c.Get("foo"); found {
-		foo := x.(*MyStruct)
+		foo := x
 			// ...
 	}
 }

go.mod

@@ -0,0 +1,5 @@
+module github.com/patrickmn/go-cache
+
+go 1.18
+
+require golang.org/x/exp v0.0.0-20220318154914-8dddf5d87bd8

go.sum

@@ -0,0 +1,2 @@
+golang.org/x/exp v0.0.0-20220318154914-8dddf5d87bd8 h1:s/+U+w0teGzcoH2mdIlFQ6KfVKGaYpgyGdUefZrn9TU=
+golang.org/x/exp v0.0.0-20220318154914-8dddf5d87bd8/go.mod h1:lgLbSvA5ygNOMpwM/9anMpWVlVJ7Z+cHWq/eFuinpGE=

ordered.go

@@ -0,0 +1,75 @@
+package cache
+
+import (
+	"fmt"
+	"time"
+
+	"golang.org/x/exp/constraints"
+)
+
+type OrderedCache[K comparable, V constraints.Ordered] struct {
+	*orderedCache[K, V]
+}
+
+type orderedCache[K comparable, V constraints.Ordered] struct {
+	*Cache[K, V]
+}
+
+// Increment an item of type by n.
+// Returns incremented item or an error if it was not found.
+func (c *orderedCache[K, V]) Increment(k K, n V) (V, error) {
+	var zeroValue V
+	c.mu.Lock()
+	v, found := c.items[k]
+	if !found || v.Expired() {
+		c.mu.Unlock()
+		return zeroValue, fmt.Errorf("Item %v not found", k)
+	}
+	res := v.Object + n
+	v.Object = res
+	c.items[k] = v
+	c.mu.Unlock()
+	return res, nil
+}
+
+// Return a new ordered cache with a given default expiration duration and cleanup
+// interval. If the expiration duration is less than one (or NoExpiration),
+// the items in the cache never expire (by default), and must be deleted
+// manually. If the cleanup interval is less than one, expired items are not
+// deleted from the cache before calling c.DeleteExpired().
+func NewOrderedCache[K comparable, V constraints.Ordered](defaultExpiration, cleanupInterval time.Duration) *OrderedCache[K, V] {
+	return &OrderedCache[K, V]{
+		orderedCache: &orderedCache[K, V]{
+			Cache: New[K, V](defaultExpiration, cleanupInterval),
+		},
+	}
+}
+
+// Return a new ordered cache with a given default expiration duration and cleanup
+// interval. If the expiration duration is less than one (or NoExpiration),
+// the items in the cache never expire (by default), and must be deleted
+// manually. If the cleanup interval is less than one, expired items are not
+// deleted from the cache before calling c.DeleteExpired().
+//
+// NewFrom() also accepts an items map which will serve as the underlying map
+// for the cache. This is useful for starting from a deserialized cache
+// (serialized using e.g. gob.Encode() on c.Items()), or passing in e.g.
+// make(map[string]Item[int], 500) to improve startup performance when the cache
+// is expected to reach a certain minimum size.
+//
+// Only the cache's methods synchronize access to this map, so it is not
+// recommended to keep any references to the map around after creating a cache.
+// If need be, the map can be accessed at a later point using c.Items() (subject
+// to the same caveat.)
+//
+// Note regarding serialization: When using e.g. gob, make sure to
+// gob.Register() the individual types stored in the cache before encoding a
+// map retrieved with c.Items(), and to register those same types before
+// decoding a blob containing an items map.
+func NewOrderedCacheFrom[K comparable, V constraints.Ordered](defaultExpiration, cleanupInterval time.Duration, items map[K]Item[V]) *OrderedCache[K, V] {
+	return &OrderedCache[K, V]{
+		orderedCache: &orderedCache[K, V]{
+			Cache: NewFrom(defaultExpiration, cleanupInterval, items),
+		},
+	}
+}

ordered_test.go

@@ -0,0 +1,84 @@
+package cache
+
+import "testing"
+
+func TestIncrementWithInt(t *testing.T) {
+	tc := NewOrderedCache[string, int](DefaultExpiration, 0)
+	tc.Set("tint", 1, DefaultExpiration)
+	n, err := tc.Increment("tint", 2)
+	if err != nil {
+		t.Error("Error incrementing:", err)
+	}
+	if n != 3 {
+		t.Error("Returned number is not 3:", n)
+	}
+	x, found := tc.Get("tint")
+	if !found {
+		t.Error("tint was not found")
+	}
+	if x != 3 {
+		t.Error("tint is not 3:", x)
+	}
+}
+
+func TestIncrementInt8(t *testing.T) {
+	tc := NewOrderedCache[string, int8](DefaultExpiration, 0)
+	tc.Set("int8", 1, DefaultExpiration)
+	n, err := tc.Increment("int8", 2)
+	if err != nil {
+		t.Error("Error decrementing:", err)
+	}
+	if n != 3 {
+		t.Error("Returned number is not 3:", n)
+	}
+	x, found := tc.Get("int8")
+	if !found {
+		t.Error("int8 was not found")
+	}
+	if x != 3 {
+		t.Error("int8 is not 3:", x)
+	}
+}
+
+func TestIncrementOverflowInt(t *testing.T) {
+	tc := NewOrderedCache[string, int8](DefaultExpiration, 0)
+	tc.Set("int8", 127, DefaultExpiration)
+	n, err := tc.Increment("int8", 1)
+	if err != nil {
+		t.Error("Error incrementing int8:", err)
+	}
+	if n != -128 {
+		t.Error("Returned number is not -128:", n)
+	}
+	x, _ := tc.Get("int8")
+	if x != -128 {
+		t.Error("int8 did not overflow as expected; value:", x)
+	}
+
+}
+
+func TestIncrementOverflowUint(t *testing.T) {
+	tc := NewOrderedCache[string, uint8](DefaultExpiration, 0)
+	tc.Set("uint8", 255, DefaultExpiration)
+	n, err := tc.Increment("uint8", 1)
+	if err != nil {
+		t.Error("Error incrementing int8:", err)
+	}
+	if n != 0 {
+		t.Error("Returned number is not 0:", n)
+	}
+	x, _ := tc.Get("uint8")
+	if x != 0 {
+		t.Error("uint8 did not overflow as expected; value:", x)
+	}
+}
+
+func BenchmarkIncrement(b *testing.B) {
+	b.StopTimer()
+	tc := NewOrderedCache[string, int](DefaultExpiration, 0)
+	tc.Set("foo", 0, DefaultExpiration)
+	b.StartTimer()
+	for i := 0; i < b.N; i++ {
+		tc.Increment("foo", 1)
+	}
+}

sharded.go

@@ -8,6 +8,8 @@ import (
 	"os"
 	"runtime"
 	"time"
+
+	"golang.org/x/exp/constraints"
 )
 
 // This is an experimental and unexported (for now) attempt at making a cache
@@ -19,15 +21,15 @@ import (
 //
 // See cache_test.go for a few benchmarks.
 
-type unexportedShardedCache struct {
+type unexportedShardedCache[V constraints.Ordered] struct {
-	*shardedCache
+	*shardedCache[V]
 }
 
-type shardedCache struct {
+type shardedCache[V constraints.Ordered] struct {
 	seed    uint32
 	m       uint32
-	cs      []*cache
+	cs      []*orderedCache[string, V]
-	janitor *shardedJanitor
+	janitor *shardedJanitor[V]
 }
 
 // djb2 with better shuffling. 5x faster than FNV with the hash.Hash overhead.
@@ -62,43 +64,36 @@ func djb33(seed uint32, k string) uint32 {
 	return d ^ (d >> 16)
 }
 
-func (sc *shardedCache) bucket(k string) *cache {
+func (sc *shardedCache[V]) bucket(k string) *orderedCache[string, V] {
 	return sc.cs[djb33(sc.seed, k)%sc.m]
 }
 
-func (sc *shardedCache) Set(k string, x interface{}, d time.Duration) {
+func (sc *shardedCache[V]) Set(k string, x V, d time.Duration) {
 	sc.bucket(k).Set(k, x, d)
 }
 
-func (sc *shardedCache) Add(k string, x interface{}, d time.Duration) error {
+func (sc *shardedCache[V]) Add(k string, x V, d time.Duration) error {
 	return sc.bucket(k).Add(k, x, d)
 }
 
-func (sc *shardedCache) Replace(k string, x interface{}, d time.Duration) error {
+func (sc *shardedCache[V]) Replace(k string, x V, d time.Duration) error {
 	return sc.bucket(k).Replace(k, x, d)
 }
 
-func (sc *shardedCache) Get(k string) (interface{}, bool) {
+func (sc *shardedCache[V]) Get(k string) (V, bool) {
 	return sc.bucket(k).Get(k)
 }
 
-func (sc *shardedCache) Increment(k string, n int64) error {
+func (sc *shardedCache[V]) Increment(k string, n V) error {
-	return sc.bucket(k).Increment(k, n)
+	_, err := sc.bucket(k).Increment(k, n)
+	return err
 }
 
-func (sc *shardedCache) IncrementFloat(k string, n float64) error {
+func (sc *shardedCache[V]) Delete(k string) {
-	return sc.bucket(k).IncrementFloat(k, n)
-}
-
-func (sc *shardedCache) Decrement(k string, n int64) error {
-	return sc.bucket(k).Decrement(k, n)
-}
-
-func (sc *shardedCache) Delete(k string) {
 	sc.bucket(k).Delete(k)
 }
 
-func (sc *shardedCache) DeleteExpired() {
+func (sc *shardedCache[V]) DeleteExpired() {
 	for _, v := range sc.cs {
 		v.DeleteExpired()
 	}
@@ -109,26 +104,26 @@ func (sc *shardedCache) DeleteExpired() {
 // fields of the items should be checked. Note that explicit synchronization
 // is needed to use a cache and its corresponding Items() return values at
 // the same time, as the maps are shared.
-func (sc *shardedCache) Items() []map[string]Item {
+func (sc *shardedCache[V]) Items() []map[string]Item[V] {
-	res := make([]map[string]Item, len(sc.cs))
+	res := make([]map[string]Item[V], len(sc.cs))
 	for i, v := range sc.cs {
 		res[i] = v.Items()
 	}
 	return res
 }
 
-func (sc *shardedCache) Flush() {
+func (sc *shardedCache[V]) Flush() {
 	for _, v := range sc.cs {
 		v.Flush()
 	}
 }
 
-type shardedJanitor struct {
+type shardedJanitor[V constraints.Ordered] struct {
 	Interval time.Duration
 	stop     chan bool
 }
 
-func (j *shardedJanitor) Run(sc *shardedCache) {
+func (j *shardedJanitor[V]) Run(sc *shardedCache[V]) {
 	j.stop = make(chan bool)
 	tick := time.Tick(j.Interval)
 	for {
@@ -141,19 +136,19 @@ func (j *shardedJanitor) Run(sc *shardedCache) {
 	}
 }
 
-func stopShardedJanitor(sc *unexportedShardedCache) {
+func stopShardedJanitor[V constraints.Ordered](sc *unexportedShardedCache[V]) {
 	sc.janitor.stop <- true
 }
 
-func runShardedJanitor(sc *shardedCache, ci time.Duration) {
+func runShardedJanitor[V constraints.Ordered](sc *shardedCache[V], ci time.Duration) {
-	j := &shardedJanitor{
+	j := &shardedJanitor[V]{
 		Interval: ci,
 	}
 	sc.janitor = j
 	go j.Run(sc)
 }
 
-func newShardedCache(n int, de time.Duration) *shardedCache {
+func newShardedCache[V constraints.Ordered](n int, de time.Duration) *shardedCache[V] {
 	max := big.NewInt(0).SetUint64(uint64(math.MaxUint32))
 	rnd, err := rand.Int(rand.Reader, max)
 	var seed uint32
@@ -163,30 +158,34 @@ func newShardedCache(n int, de time.Duration) *shardedCache {
 	} else {
 		seed = uint32(rnd.Uint64())
 	}
-	sc := &shardedCache{
+	sc := &shardedCache[V]{
 		seed: seed,
 		m:    uint32(n),
-		cs:   make([]*cache, n),
+		cs:   make([]*orderedCache[string, V], n),
 	}
 	for i := 0; i < n; i++ {
-		c := &cache{
+		c := &orderedCache[string, V]{
+			Cache: &Cache[string, V]{
+				cache: &cache[string, V]{
 					defaultExpiration: de,
-			items:             map[string]Item{},
+					items:             map[string]Item[V]{},
+				},
+			},
 		}
 		sc.cs[i] = c
 	}
 	return sc
 }
 
-func unexportedNewSharded(defaultExpiration, cleanupInterval time.Duration, shards int) *unexportedShardedCache {
+func unexportedNewSharded[V constraints.Ordered](defaultExpiration, cleanupInterval time.Duration, shards int) *unexportedShardedCache[V] {
 	if defaultExpiration == 0 {
 		defaultExpiration = -1
 	}
-	sc := newShardedCache(shards, defaultExpiration)
+	sc := newShardedCache[V](shards, defaultExpiration)
-	SC := &unexportedShardedCache{sc}
+	SC := &unexportedShardedCache[V]{sc}
 	if cleanupInterval > 0 {
 		runShardedJanitor(sc, cleanupInterval)
-		runtime.SetFinalizer(SC, stopShardedJanitor)
+		runtime.SetFinalizer(SC, stopShardedJanitor[V])
 	}
 	return SC
 }

sharded_test.go

@@ -27,7 +27,7 @@ var shardedKeys = []string{
 }
 
 func TestShardedCache(t *testing.T) {
-	tc := unexportedNewSharded(DefaultExpiration, 0, 13)
+	tc := unexportedNewSharded[string](DefaultExpiration, 0, 13)
 	for _, v := range shardedKeys {
 		tc.Set(v, "value", DefaultExpiration)
 	}
@@ -43,7 +43,7 @@ func BenchmarkShardedCacheGetNotExpiring(b *testing.B) {
 
 func benchmarkShardedCacheGet(b *testing.B, exp time.Duration) {
 	b.StopTimer()
-	tc := unexportedNewSharded(exp, 0, 10)
+	tc := unexportedNewSharded[string](exp, 0, 10)
 	tc.Set("foobarba", "zquux", DefaultExpiration)
 	b.StartTimer()
 	for i := 0; i < b.N; i++ {
@@ -62,7 +62,7 @@ func BenchmarkShardedCacheGetManyConcurrentNotExpiring(b *testing.B) {
 func benchmarkShardedCacheGetManyConcurrent(b *testing.B, exp time.Duration) {
 	b.StopTimer()
 	n := 10000
-	tsc := unexportedNewSharded(exp, 0, 20)
+	tsc := unexportedNewSharded[string](exp, 0, 20)
 	keys := make([]string, n)
 	for i := 0; i < n; i++ {
 		k := "foo" + strconv.Itoa(i)