docs

Author: agkloop

.gitignore

@@ -62,5 +62,5 @@ debug/      # Common directory for debug artifacts
 # Delve Debugger
 __debug_bin*
 qodana.yaml
-memprofile.out
-profile.out
+cmd
+testing

README.md

@@ -8,6 +8,7 @@
 - Memoizes functions with TTL, supporting 0 to 7 comparable parameters. [List of Memoize Functions](https://github.com/AhmedGoudaa/go_memoize/blob/main/memoize.go)
 - High performance, zero allocation, and zero dependencies.
 - Utilizes the FNV-1a hash algorithm for caching.
+- Thread-safe and concurrent-safe.
 
 
 ## Installation

cache.go

@@ -6,20 +6,21 @@ import (
 	"time"
 )
 
+// zeroValue returns the zero value for any type T.
 func zeroValue[T any]() T {
 	var zero T
 	return zero
 }
 
-// cacheGroup manages multiple caches with a shared ticker
+// cacheGroup manages multiple caches with a shared ticker.
 type cacheGroup struct {
 	now          atomic.Value
 	ticker       *time.Ticker
 	tickInterval time.Duration
 	done         chan struct{}
 }
 
-// NewCacheGroup creates a new cache group with shared ticker
+// newCacheGroup creates a new cache group with a shared ticker.
 func newCacheGroup() *cacheGroup {
 	group := &cacheGroup{
 		done:         make(chan struct{}),
@@ -30,6 +31,7 @@ func newCacheGroup() *cacheGroup {
 	return group
 }
 
+// startTicker starts the ticker for the cache group.
 func (g *cacheGroup) startTicker() {
 	g.ticker = time.NewTicker(g.tickInterval) // Initialize the ticker
 	go func() {
@@ -45,18 +47,16 @@ func (g *cacheGroup) startTicker() {
 	}()
 }
 
-//func (g *cacheGroup) stop() {
-//	close(g.done)
-//	g.ticker = nil
-//}
-
+// var cacheGroupInstance is a singleton instance of cacheGroup.
 var cacheGroupInstance = newCacheGroup()
 
+// entry represents a cache entry with a value and a timestamp.
 type entry[V any] struct {
 	value     V
 	timeStamp int64
 }
 
+// Cache is a generic cache with a time-to-live (TTL) for each entry.
 type Cache[K comparable, V any] struct {
 	Entries    map[K]entry[V]
 	ttl        int64
@@ -65,6 +65,7 @@ type Cache[K comparable, V any] struct {
 	zeroVal    V
 }
 
+// NewCache creates a new cache with the specified TTL.
 func NewCache[K comparable, V any](ttl int64) *Cache[K, V] {
 	return &Cache[K, V]{
 		Entries:    make(map[K]entry[V]),
@@ -74,6 +75,7 @@ func NewCache[K comparable, V any](ttl int64) *Cache[K, V] {
 	}
 }
 
+// NewCacheSized creates a new cache with the specified size and TTL.
 func NewCacheSized[K comparable, V any](size int, ttl int64) *Cache[K, V] {
 	return &Cache[K, V]{
 		Entries:    make(map[K]entry[V], size),
@@ -83,11 +85,12 @@ func NewCacheSized[K comparable, V any](size int, ttl int64) *Cache[K, V] {
 	}
 }
 
+// NowUnix returns the current Unix timestamp from the cache group.
 func (c *Cache[K, V]) NowUnix() int64 {
 	return c.cacheGroup.now.Load().(int64)
 }
 
-// inlined get and set
+// GetOrCompute retrieves the value for the given key or computes it using the provided function if not present or expired.
 func (c *Cache[K, V]) GetOrCompute(key K, computeFn func() V) V {
 	c.mu.RLock()
 	existingEntry, ok := c.Entries[key]
@@ -105,19 +108,22 @@ func (c *Cache[K, V]) GetOrCompute(key K, computeFn func() V) V {
 	return newVal
 }
 
+// Delete removes the entry for the given key from the cache.
 func (c *Cache[K, V]) Delete(key K) {
 	c.mu.Lock()
 	delete(c.Entries, key)
 	c.mu.Unlock()
 }
 
+// Set adds or updates the value for the given key in the cache.
 func (c *Cache[K, V]) Set(key K, value V) {
 	timeStamp := c.NowUnix()
 	c.mu.Lock()
 	c.Entries[key] = entry[V]{value: value, timeStamp: timeStamp}
 	c.mu.Unlock()
 }
 
+// Get retrieves the value for the given key from the cache if present and not expired.
 func (c *Cache[K, V]) Get(key K) (V, bool) {
 	c.mu.RLock()
 	entry, ok := c.Entries[key]

hashing.go

@@ -29,34 +29,50 @@ const (
 	falseHash = offset64 ^ 0*prime64
 )
 
+// hash1 hashes a single key using the FNV-1a algorithm.
+// A is a comparable type.
 func hash1[A comparable](key A) uint64 {
 	return hash(offset64, key)
 }
 
+// hash2 hashes two keys using the FNV-1a algorithm.
+// A and B are comparable types.
 func hash2[A, B comparable](key1 A, key2 B) uint64 {
 	return hash(hash(offset64, key1), key2)
 }
 
+// hash3 hashes three keys using the FNV-1a algorithm.
+// A, B, and C are comparable types.
 func hash3[A, B, C comparable](key1 A, key2 B, key3 C) uint64 {
 	return hash(hash(hash(offset64, key1), key2), key3)
 }
 
+// hash4 hashes four keys using the FNV-1a algorithm.
+// A, B, C, and D are comparable types.
 func hash4[A, B, C, D comparable](key1 A, key2 B, key3 C, key4 D) uint64 {
 	return hash(hash(hash(hash(offset64, key1), key2), key3), key4)
 }
 
+// hash5 hashes five keys using the FNV-1a algorithm.
+// A, B, C, D, and E are comparable types.
 func hash5[A, B, C, D, E comparable](key1 A, key2 B, key3 C, key4 D, key5 E) uint64 {
 	return hash(hash(hash(hash(hash(offset64, key1), key2), key3), key4), key5)
 }
 
+// hash6 hashes six keys using the FNV-1a algorithm.
+// A, B, C, D, E, and F are comparable types.
 func hash6[A, B, C, D, E, F comparable](key1 A, key2 B, key3 C, key4 D, key5 E, key6 F) uint64 {
 	return hash(hash(hash(hash(hash(hash(offset64, key1), key2), key3), key4), key5), key6)
 }
 
+// hash7 hashes seven keys using the FNV-1a algorithm.
+// A, B, C, D, E, F, and G are comparable types.
 func hash7[A, B, C, D, E, F, G comparable](key1 A, key2 B, key3 C, key4 D, key5 E, key6 F, key7 G) uint64 {
 	return hash(hash(hash(hash(hash(hash(hash(offset64, key1), key2), key3), key4), key5), key6), key7)
 }
 
+// hash hashes a key using the FNV-1a algorithm.
+// A is a comparable type.
 func hash[A comparable](hash uint64, key A) uint64 {
 	switch v := any(key).(type) {
 	case string:
@@ -94,13 +110,7 @@ func hash[A comparable](hash uint64, key A) uint64 {
 	}
 }
 
-//func hashString(hash uint64, key string) uint64 {
-//	for i := 0; i < len(key); i++ {
-//		hash = (hash ^ uint64(key[i])) * prime64
-//	}
-//	return hash
-//}
-
+// hashString hashes a string key using the FNV-1a algorithm.
 func hashString(hash uint64, key string) uint64 {
 	length := len(key)
 
@@ -118,22 +128,26 @@ func hashString(hash uint64, key string) uint64 {
 	}
 	return hash
 }
+
+// hashInt hashes an integer key using the FNV-1a algorithm.
 func hashInt(hash uint64, key uint64) uint64 {
 	return (hash ^ key) * prime64
 }
 
+// hashUint hashes an unsigned integer key using the FNV-1a algorithm.
 func hashUint(hash uint64, key uint64) uint64 {
 	return (hash ^ key) * prime64
 }
 
+// hashFloat hashes a floating-point key using the FNV-1a algorithm.
 func hashFloat(hash uint64, key uint64) uint64 {
 	return (hash ^ key) * prime64
 }
 
+// hashBool hashes a boolean key using the FNV-1a algorithm.
 func hashBool(key bool) uint64 {
 	if key {
 		return trueHash
 	}
 	return falseHash
-
 }

memoize.go

@@ -4,6 +4,8 @@ import (
 	"time"
 )
 
+// Memoize returns a memoized version of the compute function with a specified TTL.
+// V is the type of the value returned by the compute function.
 func Memoize[V any](computeFn func() V, ttl time.Duration) func() V {
 	cache := NewCacheSized[uint64, V](1, int64(ttl.Seconds()))
 	return func() V {
@@ -13,6 +15,8 @@ func Memoize[V any](computeFn func() V, ttl time.Duration) func() V {
 	}
 }
 
+// Memoize1 returns a memoized version of the compute function with a single key and a specified TTL.
+// K is the type of the key, and V is the type of the value returned by the compute function.
 func Memoize1[K comparable, V any](computeFn func(K) V, ttl time.Duration) func(K) V {
 	cache := NewCache[uint64, V](int64(ttl.Seconds()))
 	return func(k K) V {
@@ -22,6 +26,8 @@ func Memoize1[K comparable, V any](computeFn func(K) V, ttl time.Duration) func(
 	}
 }
 
+// Memoize2 returns a memoized version of the compute function with two keys and a specified TTL.
+// K1 and K2 are the types of the keys, and V is the type of the value returned by the compute function.
 func Memoize2[K1, K2 comparable, V any](computeFn func(K1, K2) V, ttl time.Duration) func(K1, K2) V {
 	cache := NewCache[uint64, V](int64(ttl.Seconds()))
 	return func(key1 K1, key2 K2) V {
@@ -30,6 +36,9 @@ func Memoize2[K1, K2 comparable, V any](computeFn func(K1, K2) V, ttl time.Durat
 		})
 	}
 }
+
+// Memoize3 returns a memoized version of the compute function with three keys and a specified TTL.
+// K1, K2, and K3 are the types of the keys, and V is the type of the value returned by the compute function.
 func Memoize3[K1, K2, K3 comparable, V any](computeFn func(K1, K2, K3) V, ttl time.Duration) func(K1, K2, K3) V {
 	cache := NewCache[uint64, V](int64(ttl.Seconds()))
 	return func(key1 K1, key2 K2, key3 K3) V {
@@ -39,6 +48,8 @@ func Memoize3[K1, K2, K3 comparable, V any](computeFn func(K1, K2, K3) V, ttl ti
 	}
 }
 
+// Memoize4 returns a memoized version of the compute function with four keys and a specified TTL.
+// K1, K2, K3, and K4 are the types of the keys, and V is the type of the value returned by the compute function.
 func Memoize4[K1, K2, K3, K4 comparable, V any](computeFn func(K1, K2, K3, K4) V, ttl time.Duration) func(K1, K2, K3, K4) V {
 	cache := NewCache[uint64, V](int64(ttl.Seconds()))
 	return func(key1 K1, key2 K2, key3 K3, key4 K4) V {
@@ -48,6 +59,8 @@ func Memoize4[K1, K2, K3, K4 comparable, V any](computeFn func(K1, K2, K3, K4) V
 	}
 }
 
+// Memoize5 returns a memoized version of the compute function with five keys and a specified TTL.
+// K1, K2, K3, K4, and K5 are the types of the keys, and V is the type of the value returned by the compute function.
 func Memoize5[K1, K2, K3, K4, K5 comparable, V any](computeFn func(K1, K2, K3, K4, K5) V, ttl time.Duration) func(K1, K2, K3, K4, K5) V {
 	cache := NewCache[uint64, V](int64(ttl.Seconds()))
 	return func(key1 K1, key2 K2, key3 K3, key4 K4, key5 K5) V {
@@ -57,6 +70,8 @@ func Memoize5[K1, K2, K3, K4, K5 comparable, V any](computeFn func(K1, K2, K3, K
 	}
 }
 
+// Memoize6 returns a memoized version of the compute function with six keys and a specified TTL.
+// K1, K2, K3, K4, K5, and K6 are the types of the keys, and V is the type of the value returned by the compute function.
 func Memoize6[K1, K2, K3, K4, K5, K6 comparable, V any](computeFn func(K1, K2, K3, K4, K5, K6) V, ttl time.Duration) func(K1, K2, K3, K4, K5, K6) V {
 	cache := NewCache[uint64, V](int64(ttl.Seconds()))
 	return func(key1 K1, key2 K2, key3 K3, key4 K4, key5 K5, key6 K6) V {
@@ -66,6 +81,8 @@ func Memoize6[K1, K2, K3, K4, K5, K6 comparable, V any](computeFn func(K1, K2, K
 	}
 }
 
+// Memoize7 returns a memoized version of the compute function with seven keys and a specified TTL.
+// K1, K2, K3, K4, K5, K6, and K7 are the types of the keys, and V is the type of the value returned by the compute function.
 func Memoize7[K1, K2, K3, K4, K5, K6, K7 comparable, V any](computeFn func(K1, K2, K3, K4, K5, K6, K7) V, ttl time.Duration) func(K1, K2, K3, K4, K5, K6, K7) V {
 	cache := NewCache[uint64, V](int64(ttl.Seconds()))
 	return func(key1 K1, key2 K2, key3 K3, key4 K4, key5 K5, key6 K6, key7 K7) V {