Add configurable pruneFactor

Author: Tim Middleton

coherence/coherence_test_helpers.go

@@ -122,6 +122,15 @@ func GetSessionQueueID(session *Session, queue string) *int32 {
 	return session.getQueueID(queue)
 }
 
+func GetNearCachePruneFactor[K comparable, V any](namedMap NamedMap[K, V]) float32 {
+	ncOptions := namedMap.getBaseClient().cacheOpts.NearCacheOptions
+	if ncOptions == nil {
+		return 0.0
+	}
+
+	return ncOptions.PruneFactor
+}
+
 // revive:disable:unexported-return
 func GetKeyListenerGroupMap[K comparable, V any](namedMap NamedMap[K, V]) map[K]*listenerGroupV1[K, V] {
 	return namedMap.getBaseClient().keyListenersV1

coherence/common.go

@@ -103,15 +103,26 @@ type CacheOptions struct {
 
 // NearCacheOptions defines options when creating a near cache.
 type NearCacheOptions struct {
-	TTL                  time.Duration
-	HighUnits            int64
-	HighUnitsMemory      int64
+	// TTL is the maximum time to keep the entry in the near cache. When this time has been reached it will be expired.
+	TTL time.Duration
+
+	// HighUnits is the maximum number of cache entries to keep in the near cache.
+	HighUnits int64
+
+	// HighUnitsMemory is the maximum amount of memory to use for entries in the near cache.
+	HighUnitsMemory int64
+
 	InvalidationStrategy InvalidationStrategyType // currently only supports ListenAll
+
+	// PruneFactor indicates the percentage of the total number of units that will remain
+	// after the cache manager prunes the near cache(i.e. this is the "low watermark" value)
+	// this value is in the range 0.1 to 1.0 and the default is 0.8 or 80%.
+	PruneFactor float32
 }
 
 func (n NearCacheOptions) String() string {
-	return fmt.Sprintf("NearCacheOptions{TTL=%v, HighUnits=%v, HighUnitsMemory=%v, invalidationStrategy=%v}",
-		n.TTL, n.HighUnits, n.HighUnitsMemory, getInvalidationStrategyString(n.InvalidationStrategy))
+	return fmt.Sprintf("NearCacheOptions{TTL=%v, HighUnits=%v, HighUnitsMemory=%v, PruneFactor=%.2f, invalidationStrategy=%v}",
+		n.TTL, n.HighUnits, n.HighUnitsMemory, n.PruneFactor, getInvalidationStrategyString(n.InvalidationStrategy))
 }
 
 // WithExpiry returns a function to set the default expiry for a [NamedCache]. This option is not valid on [NamedMap].

coherence/doc.go

@@ -774,9 +774,13 @@ The following example shows how to get a named cache that will cache entries fro
 2. Creating a Near Cache specifying maximum number of entries to store
 
 The following example shows how to get a named cache that will cache up to 100 entries from Get() or GetAll().
-When the threshold of HighUnits is reached, the near cache is pruned to 80% of its size and evicts least recently
+When the threshold of HighUnits is reached, the near cache is pruned to the default of 80% of its size and evicts least recently
 accessed and created entries.
 
+Note: The default prune percentage is 0.8 (80%) which indicates the percentage of the total number of
+units that will remain after the cache manager prunes the near cache( i.e. this is the "low watermark" value).
+This can be changed by setting the PruneFactory to a value in the range 0.1 to 1.0 in [NearCacheOptions].
+
 	// specify HighUnits of 1000
 	nearCacheOptions := coherence.NearCacheOptions{HighUnits: 1000}
 
@@ -827,8 +831,8 @@ accessed and created entries.
 
 	// print the near cache stats via String()
 	fmt.Println(namedMap.GetNearCacheStats())
-	// localCache{name=customers options=localCacheOptions{ttl=0s, highUnits=0, highUnitsMemory=10.0KB, invalidation=ListenAll},
-	// stats=CacheStats{puts=5000, gets=5000, hits=0, misses=5000, missesDuration=4.95257111s, hitRate=0, prunes=7, prunesDuration=196.498µs, size=398, memoryUsed=9.3KB}}
+	// localCache{name=my-near-cache-high-units, options=localCacheOptions{ttl=0s, highUnits=1000, highUnitsMemory=0B, pruneFactor=0.80, invalidation=ListenAll}, stats=CacheStats{puts=1001, gets=1002, hits=1, misses=1001, missesDuration=4.628931138s,
+	// hitRate=0.0998004, prunes=1, prunesDuration=181.533µs, expires=0, expiresDuration=0s, size=200, memoryUsed=53.2KB}}
 
 [Coherence Documentation]: https://docs.oracle.com/en/middleware/standalone/coherence/14.1.1.2206/develop-applications/introduction-coherence-caches.html
 [examples]: https://github.com/oracle/coherence-go-client/tree/main/examples

coherence/localcache.go

@@ -24,10 +24,10 @@ var (
 )
 
 const (
-	KB           = 1024
-	MB           = KB * KB
-	GB           = MB * KB
-	prunePercent = 20
+	KB                         = 1024
+	MB                         = KB * KB
+	GB                         = MB * KB
+	defaultPruneFactor float32 = 0.8 // prune to 80%
 )
 
 // localCache implements a local cache of values.
@@ -271,9 +271,9 @@ func (l *localCacheImpl[K, V]) pruneEntries() {
 			l.registerPruneNanos(time.Since(start).Nanoseconds())
 		}()
 
-		entriesToDelete := int(math.Round(float64(currentCacheSize * prunePercent / 100.0)))
+		entriesToDelete := int(math.Round(float64(float32(currentCacheSize) * (1 - l.options.PruneFactor))))
 
-		// prune to default of 80% of the cache size.
+		// prune to default of l.options.PruneFactor % of the cache size.
 		// we first sort the map by lastAccess time / then insert time, so we remove all
 		// entries firstly that have never been accessed.
 		index := 0
@@ -329,6 +329,10 @@ func newLocalCache[K comparable, V any](name string, options ...func(localCache
 		f(cache.options)
 	}
 
+	if cache.options.PruneFactor == 0 {
+		cache.options.PruneFactor = defaultPruneFactor
+	}
+
 	return cache
 }
 
@@ -338,11 +342,12 @@ type localCacheOptions struct {
 	HighUnits            int64
 	HighUnitsMemory      int64
 	InvalidationStrategy InvalidationStrategyType
+	PruneFactor          float32
 }
 
 func (o *localCacheOptions) String() string {
-	return fmt.Sprintf("localCacheOptions{ttl=%v, highUnits=%v, highUnitsMemory=%v, invalidation=%v}",
-		o.TTL, o.HighUnits, formatMemory(o.HighUnitsMemory), getInvalidationStrategyString(o.InvalidationStrategy))
+	return fmt.Sprintf("localCacheOptions{ttl=%v, highUnits=%v, highUnitsMemory=%v, pruneFactor=%.2f, invalidation=%v}",
+		o.TTL, o.HighUnits, formatMemory(o.HighUnitsMemory), o.PruneFactor, getInvalidationStrategyString(o.InvalidationStrategy))
 }
 
 // withLocalCacheExpiry returns a function to set the expiry time for a local cache.
@@ -373,6 +378,13 @@ func withLocalCacheHighUnitsMemory(highUnitsMemory int64) func(options *localCac
 	}
 }
 
+// withPruneFactor returns a function to set the prune factor for a local cache.
+func withPruneFactor(pruneFactor float32) func(options *localCacheOptions) {
+	return func(o *localCacheOptions) {
+		o.PruneFactor = pruneFactor
+	}
+}
+
 func (l *localCacheImpl[K, V]) registerHit() {
 	atomic.AddInt64(&l.cacheHits, 1)
 }

coherence/localcache_test.go

@@ -8,6 +8,7 @@ package coherence
 import (
 	"fmt"
 	"github.com/onsi/gomega"
+	"math"
 	"sync"
 	"testing"
 	"time"
@@ -148,7 +149,9 @@ func TestLocalCacheWithHighUnitsOnly(t *testing.T) {
 	// put a new entry which should cause prune of 20 entries
 	cache.Put(100, "one hundred")
 
-	g.Expect(cache.Size()).To(gomega.Equal(80))
+	expectedSize := int(math.Round(float64(float32(100) * cache.options.PruneFactor)))
+
+	g.Expect(cache.Size()).To(gomega.Equal(expectedSize))
 	g.Expect(cache.GetCachePrunes()).To(gomega.Equal(int64(1)))
 	fmt.Println(cache)
 }
@@ -189,7 +192,9 @@ func TestLocalCacheWithHighUnitsOnlyAccessTime(t *testing.T) {
 	// put a new entry which should cause prune of 20 entries
 	cache.Put(100, "one hundred")
 
-	g.Expect(cache.Size()).To(gomega.Equal(80))
+	expectedSize := int(math.Round(float64(float32(100) * cache.options.PruneFactor)))
+
+	g.Expect(cache.Size()).To(gomega.Equal(expectedSize))
 	g.Expect(cache.GetCachePrunes()).To(gomega.Equal(int64(1)))
 
 	// entries 1, 2 and three should not be removed as they were accessed

coherence/named_cache_client.go

@@ -839,6 +839,10 @@ func validateNearCacheOptions(options *NearCacheOptions) error {
 		return ErrNegativeNearCacheOptions
 	}
 
+	if options.PruneFactor != 0 && options.PruneFactor < 0.1 || options.PruneFactor > 1 {
+		return ErrInvalidPruneFactor
+	}
+
 	if options.TTL == 0 && options.HighUnits == 0 && options.HighUnitsMemory == 0 {
 		return ErrInvalidNearCache
 	}

coherence/named_map_client.go

@@ -1030,6 +1030,14 @@ func newBaseClient[K comparable, V any](session *Session, name string, format st
 		if bc.cacheOpts.NearCacheOptions.HighUnitsMemory != 0 {
 			options = append(options, withLocalCacheHighUnitsMemory(bc.cacheOpts.NearCacheOptions.HighUnitsMemory))
 		}
+
+		// default prune to defaultPruneFactor (80%) if not set
+		if bc.cacheOpts.NearCacheOptions.PruneFactor == 0 {
+			bc.cacheOpts.NearCacheOptions.PruneFactor = defaultPruneFactor
+		}
+
+		options = append(options, withPruneFactor(bc.cacheOpts.NearCacheOptions.PruneFactor))
+
 		nearCache := newLocalCache[K, V](bc.name, options...)
 		bc.nearCache = nearCache
 	}

coherence/session.go

@@ -36,6 +36,7 @@ var (
 	ErrInvalidNearCacheWithTTL   = errors.New("when using TTL for near cache you can only specify highUnits or highUnitsMemory")
 	ErrInvalidNearCacheWithNoTTL = errors.New("you can only specify highUnits or highUnitsMemory, not both")
 	ErrNegativeNearCacheOptions  = errors.New("you cannot specify negative values for near cache options")
+	ErrInvalidPruneFactor        = errors.New("prune factory must be between 0 and 1.0")
 )
 
 const (

test/e2e/standalone/near_cache_test.go

@@ -13,6 +13,7 @@ import (
 	"github.com/oracle/coherence-go-client/coherence/filters"
 	"github.com/oracle/coherence-go-client/coherence/processors"
 	"github.com/oracle/coherence-go-client/test/utils"
+	"math"
 	"testing"
 	"time"
 )
@@ -33,6 +34,7 @@ func TestNearCacheOperationsAgainstMapAndCache(t *testing.T) {
 	nearCacheOptions120Seconds := coherence.NearCacheOptions{TTL: time.Duration(120) * time.Second}
 	nearCacheOptionsHighUnits1 := coherence.NearCacheOptions{HighUnits: 100}
 	nearCacheOptionsHighUnits2 := coherence.NearCacheOptions{HighUnitsMemory: 50 * 1024}
+	nearCacheOptionsHighUnits3 := coherence.NearCacheOptions{HighUnits: 100, PruneFactor: 0.2}
 
 	testCases := []struct {
 		testName string
@@ -55,6 +57,8 @@ func TestNearCacheOperationsAgainstMapAndCache(t *testing.T) {
 		{"RunTestNearCacheGetAllNamedCache2", GetNearCacheNamedCache[int, utils.Person](g, session, "near-cache-get-all-cache2", coherence.WithNearCache(&nearCacheOptions120Seconds)), RunTestNearCacheGetAll2},
 		{"RunTestNearCacheWithHighUnitsNamedMap", GetNearCacheNamedMap[int, utils.Person](g, session, "near-cache-high-units-map", coherence.WithNearCache(&nearCacheOptionsHighUnits1)), RunTestNearCacheWithHighUnits},
 		{"RunTestNearCacheWithHighUnitsNamedCache", GetNearCacheNamedCache[int, utils.Person](g, session, "near-cache-high-units-cache", coherence.WithNearCache(&nearCacheOptionsHighUnits1)), RunTestNearCacheWithHighUnits},
+		{"RunTestNearCacheWithHighUnitsNamedMapPruneFactor", GetNearCacheNamedMap[int, utils.Person](g, session, "near-cache-high-units-map", coherence.WithNearCache(&nearCacheOptionsHighUnits3)), RunTestNearCacheWithHighUnits},
+		{"RunTestNearCacheWithHighUnitsNamedCachePruneFactor", GetNearCacheNamedCache[int, utils.Person](g, session, "near-cache-high-units-cache", coherence.WithNearCache(&nearCacheOptionsHighUnits3)), RunTestNearCacheWithHighUnits},
 		{"RunTestNearCacheWithHighUnitsMemoryNamedMap", GetNearCacheNamedMap[int, utils.Person](g, session, "near-cache-high-units-mem-map", coherence.WithNearCache(&nearCacheOptionsHighUnits2)), RunTestNearCacheWithHighUnitsMemory},
 		{"RunTestNearCacheWithHighUnitsMemoryNamedCache", GetNearCacheNamedCache[int, utils.Person](g, session, "near-cache-high-units-mem-cache", coherence.WithNearCache(&nearCacheOptionsHighUnits2)), RunTestNearCacheWithHighUnitsMemory},
 		{"RunTestNearCacheWithHighUnitsAccessNamedMap", GetNearCacheNamedMap[int, utils.Person](g, session, "near-cache-high-units-access-mem-map", coherence.WithNearCache(&nearCacheOptionsHighUnits1)), RunTestNearCacheWithHighUnitsAccess},
@@ -342,12 +346,16 @@ func RunTestNearCacheWithHighUnits(t *testing.T, namedMap coherence.NamedMap[int
 	// should have 100 entries in near cache
 	g.Expect(namedMap.GetNearCacheStats().Size()).To(gomega.Equal(100))
 
-	// issue a Get() for an entry not in the cache which will trigger the HighUnits and prune to 80 entries
+	// issue a Get() for an entry not in the cache which will trigger the HighUnits and prune entries
 	_, err = namedMap.Get(ctx, 110)
 	g.Expect(err).ShouldNot(gomega.HaveOccurred())
 
-	g.Expect(namedMap.GetNearCacheStats().Size()).To(gomega.Equal(80))
-	g.Expect(namedMap.GetNearCacheStats().GetCachePrunes()).To(gomega.Equal(int64(1)))
+	// get the current PuneFactor
+	pruneFactor := coherence.GetNearCachePruneFactor(namedMap)
+	expectedSize := int(math.Round(float64(float32(100) * pruneFactor)))
+
+	g.Expect(namedMap.GetNearCacheStats().Size()).To(gomega.Equal(expectedSize))
+	g.Expect(namedMap.GetNearCacheStats().GetCachePrunes()).ToNot(gomega.Equal(int64(0)))
 }
 
 // RunTestNearWithClear tests a near cache that issues puts, get then clears..
@@ -438,8 +446,12 @@ func RunTestNearCacheWithHighUnitsAccess(t *testing.T, namedMap coherence.NamedM
 	_, err = namedMap.Get(ctx, 110)
 	g.Expect(err).ShouldNot(gomega.HaveOccurred())
 
-	g.Expect(namedMap.GetNearCacheStats().Size()).To(gomega.Equal(80))
-	g.Expect(namedMap.GetNearCacheStats().GetCachePrunes()).To(gomega.Equal(int64(1)))
+	// get the current PuneFactor
+	pruneFactor := coherence.GetNearCachePruneFactor(namedMap)
+	expectedSize := int(math.Round(float64(float32(100) * pruneFactor)))
+
+	g.Expect(namedMap.GetNearCacheStats().Size()).To(gomega.Equal(expectedSize))
+	g.Expect(namedMap.GetNearCacheStats().GetCachePrunes()).ToNot(gomega.Equal(int64(0)))
 
 	t.Log("near cache stats before get", namedMap.GetNearCacheStats())
 
@@ -547,6 +559,30 @@ func TestDuplicateNamedCache(t *testing.T) {
 	namedMap.Release()
 }
 
+// TestNearCachePruneFactor runs tests to ensure we honor the pruneFactor.
+func TestNearCachePruneFactor(t *testing.T) {
+	g := gomega.NewWithT(t)
+
+	session, err := utils.GetSession()
+	g.Expect(err).ShouldNot(gomega.HaveOccurred())
+	defer session.Close()
+
+	// test value of 0.2
+	nearCacheOptions1 := coherence.NearCacheOptions{HighUnits: 100, PruneFactor: 0.2}
+	namedCache, err := coherence.GetNamedCache[int, string](session, nearCacheName, coherence.WithNearCache(&nearCacheOptions1))
+	g.Expect(err).ShouldNot(gomega.HaveOccurred())
+
+	// validate the factor
+	g.Expect(coherence.GetNearCachePruneFactor[int, string](namedCache)).To(gomega.Equal(nearCacheOptions1.PruneFactor))
+	namedCache.Release()
+
+	// test default value of 0.8
+	nearCacheOptions2 := coherence.NearCacheOptions{HighUnits: 100}
+	namedCache, err = coherence.GetNamedCache[int, string](session, nearCacheName, coherence.WithNearCache(&nearCacheOptions2))
+	g.Expect(err).ShouldNot(gomega.HaveOccurred())
+	g.Expect(coherence.GetNearCachePruneFactor[int, string](namedCache)).To(gomega.Equal(float32(0.8)))
+}
+
 // TestInvalidNearCacheOptions runs tests to ensure that we can't create a named cache/map with invalid options.
 func TestInvalidNearCacheOptions(t *testing.T) {
 	var (
@@ -591,6 +627,23 @@ func TestInvalidNearCacheOptions(t *testing.T) {
 	_, err = coherence.GetNamedMap[int, string](session, nearMapName, coherence.WithNearCache(&nearCacheOptionsBad3))
 	g.Expect(err).Should(gomega.HaveOccurred())
 	g.Expect(err).Should(gomega.Equal(coherence.ErrInvalidNearCacheWithNoTTL))
+
+	// cannot have Invalid PruneFactor
+	nearCacheOptionsBad4 := coherence.NearCacheOptions{HighUnits: 1000, PruneFactor: -1.0}
+	_, err = coherence.GetNamedMap[int, string](session, nearMapName, coherence.WithNearCache(&nearCacheOptionsBad4))
+	g.Expect(err).Should(gomega.HaveOccurred())
+	g.Expect(err).Should(gomega.Equal(coherence.ErrInvalidPruneFactor))
+
+	nearCacheOptionsBad4.PruneFactor = 0.05
+	_, err = coherence.GetNamedMap[int, string](session, nearMapName, coherence.WithNearCache(&nearCacheOptionsBad4))
+	g.Expect(err).Should(gomega.HaveOccurred())
+	g.Expect(err).Should(gomega.Equal(coherence.ErrInvalidPruneFactor))
+
+	nearCacheOptionsBad4.PruneFactor = 1.01
+	_, err = coherence.GetNamedMap[int, string](session, nearMapName, coherence.WithNearCache(&nearCacheOptionsBad4))
+	g.Expect(err).Should(gomega.HaveOccurred())
+	g.Expect(err).Should(gomega.Equal(coherence.ErrInvalidPruneFactor))
+
 }
 
 // TestIncompatibleNearCacheOptions runs tests to ensure that we can't create a named cache/map with incompatible.