Minor doc update, near cache calc update

Author: Tim Middleton

Makefile

@@ -244,7 +244,7 @@ generate-proto-v1: $(TOOLS_BIN)/protoc ## Generate Proto Files v1
 # ----------------------------------------------------------------------------------------------------------------------
 .PHONY: show-docs
 show-docs:   ## Show the Documentation
-	@echo "Serving documentation on http://localhost:6060/pkg/github.com/oracle/coherence-go-client/"
+	@echo "Serving documentation on http://localhost:6060/pkg/github.com/oracle/coherence-go-client/v2"
 	go install golang.org/x/tools/cmd/godoc@latest
 	godoc -goroot $(GOROOT)	-http=:6060
 
@@ -421,7 +421,7 @@ getcopyright: ## Download copyright jar locally if necessary.
 $(TOOLS_BIN)/protoc:
 	@mkdir -p $(TOOLS_BIN)
 	./scripts/download-protoc.sh $(TOOLS_DIRECTORY)
-	go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.30.0
+	go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.33.0
 	go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.3.0
 
 

coherence/event.go

@@ -60,7 +60,7 @@ const (
 // MapEventType describes an event raised by a cache mutation.
 type MapEventType string
 
-// MapLifecycleEventType describes an event that may be raised during the lifecycle
+// MapLifecycleEventType describes an event type that may be raised during the lifecycle
 // of a cache.
 type MapLifecycleEventType string
 
@@ -159,8 +159,13 @@ func (se *sessionLifecycleEvent) String() string {
 	return fmt.Sprintf("SessionLifecycleEvent{source=%v, format=%s}", se.Source(), se.Type())
 }
 
+// MapLifecycleEvent describes an event that may be raised during the lifecycle
+// of a cache.
 type MapLifecycleEvent[K comparable, V any] interface {
+	// Source returns the source of this MapLifecycleEvent.
 	Source() NamedMap[K, V]
+
+	// Type returns the MapLifecycleEventType for this MapLifecycleEvent.
 	Type() MapLifecycleEventType
 }
 
@@ -186,22 +191,39 @@ func (l *mapLifecycleEvent[K, V]) Source() NamedMap[K, V] {
 	return l.source
 }
 
-// String returns a string representation of a MapLifecycleEvent.
+// String returns a string representation of a [MapLifecycleEvent].
 func (l *mapLifecycleEvent[K, V]) String() string {
 	return fmt.Sprintf("MapLifecycleEvent{source=%v, type=%s}", l.Source().GetCacheName(), l.Type())
 }
 
-// MapEvent an event which indicates that the content of the NamedMap or
-// NamedCache has changed (i.e., an entry has been added, updated, and/or
+// MapEvent an event which indicates that the content of the [NamedMap] or
+// [NamedCache] has changed (i.e., an entry has been added, updated, and/or
 // removed).
 type MapEvent[K comparable, V any] interface {
+	// Source returns the source of this MapEvent.
 	Source() NamedMap[K, V]
+
+	// Key returns the key of the entry for which this event was raised.
 	Key() (*K, error)
+
+	// OldValue returns the old value, if any, of the entry for which this event
+	// was raised.
 	OldValue() (*V, error)
+
+	// NewValue returns the new value, if any, of the entry for which this event
+	// was raised.
 	NewValue() (*V, error)
+
+	// Type returns the MapEventType for this MapEvent.
 	Type() MapEventType
+
+	// IsExpired returns true if the event was generated from an expiry event. Only valid for gRPC v1 connections.
 	IsExpired() (bool, error)
+
+	// IsPriming returns true if the event is a priming event. Only valid for gRPC v1 connections.
 	IsPriming() (bool, error)
+
+	// IsSynthetic returns true if the event is a synthetic event. Only valid for gRPC v1 connections.
 	IsSynthetic() (bool, error)
 }
 

coherence/localcache.go

@@ -43,7 +43,7 @@ type localCache[K comparable, V any] interface {
 	GetStats() CacheStats
 }
 
-// CacheStats defines various statics for near caches.
+// CacheStats contains various statistics for near caches.
 type CacheStats interface {
 	GetCacheHits() int64                    // the number of entries served from the near cache
 	GetCacheMisses() int64                  // the number of entries that had to be retrieved from the cluster
@@ -479,7 +479,8 @@ func (l *localCacheImpl[K, V]) String() string {
 // updateEntrySize updates the cacheMemory size based upon a local entry. The sign indicates to either remove or add.
 func (l *localCacheImpl[K, V]) updateEntrySize(entry *localCacheEntry[K, V], sign int) {
 	l.updateCacheMemory(int64(sign)*(int64(unsafe.Sizeof(entry.key))+int64(unsafe.Sizeof(entry.value))+
-		(int64(unsafe.Sizeof(entry.ttl)))+(int64(unsafe.Sizeof(entry.insertTime)))) + (int64(unsafe.Sizeof(entry.lastAccess))))
+		(int64(unsafe.Sizeof(entry.ttl)))+(int64(unsafe.Sizeof(entry.insertTime)))) +
+		(int64(unsafe.Sizeof(entry.lastAccess))) + int64(unsafe.Sizeof(entry)))
 }
 
 func formatMemory(bytesValue int64) string {

coherence/queue_events.go

@@ -57,9 +57,16 @@ func (l *queueLifecycleEvent[V]) String() string {
 // QueueLifecycleListener allows registering callbacks to be notified when lifecycle events
 // (truncated, released or destroyed) occur against a [NamedQueue].
 type QueueLifecycleListener[V any] interface {
+	// OnAny registers a callback that will be notified when any [NamedQueue] event occurs.
 	OnAny(callback func(QueueLifecycleEvent[V])) QueueLifecycleListener[V]
+
+	// OnDestroyed registers a callback that will be notified when a [NamedQueue] is destroyed.
 	OnDestroyed(callback func(QueueLifecycleEvent[V])) QueueLifecycleListener[V]
+
+	// OnTruncated registers a callback that will be notified when a [Queue] is truncated.
 	OnTruncated(callback func(QueueLifecycleEvent[V])) QueueLifecycleListener[V]
+
+	// OnReleased registers a callback that will be notified when a [NamedQueue] is released.
 	OnReleased(callback func(QueueLifecycleEvent[V])) QueueLifecycleListener[V]
 	getEmitter() *eventEmitter[QueueLifecycleEventType, QueueLifecycleEvent[V]]
 }
@@ -89,7 +96,7 @@ func (q *queueLifecycleListener[V]) OnReleased(callback func(QueueLifecycleEvent
 	return q.on(QueueReleased, callback)
 }
 
-// OnTruncated registers a callback that will be notified when a [NamedMap] is truncated.
+// OnTruncated registers a callback that will be notified when a [Queue] is truncated.
 func (q *queueLifecycleListener[V]) OnTruncated(callback func(QueueLifecycleEvent[V])) QueueLifecycleListener[V] {
 	return q.on(QueueTruncated, callback)
 }
@@ -98,7 +105,7 @@ func (q *queueLifecycleListener[V]) getEmitter() *eventEmitter[QueueLifecycleEve
 	return q.emitter
 }
 
-// OnAny registers a callback that will be notified when any [NamedMap] event occurs.
+// OnAny registers a callback that will be notified when any [NamedQueue] event occurs.
 func (q *queueLifecycleListener[V]) OnAny(callback func(QueueLifecycleEvent[V])) QueueLifecycleListener[V] {
 	return q.OnTruncated(callback).OnDestroyed(callback).OnReleased(callback)
 }

coherence/serializers.go

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2023 Oracle and/or its affiliates.
+ * Copyright (c) 2022, 2024 Oracle and/or its affiliates.
  * Licensed under the Universal Permissive License v 1.0 as shown at
  * https://oss.oracle.com/licenses/upl.
  */
@@ -28,8 +28,13 @@ type mathValue[T any] struct {
 
 // Serializer defines how to serialize/ de-serialize objects.
 type Serializer[T any] interface {
+	// Serialize serializes an object of type T and returns the []byte representation.
 	Serialize(object T) ([]byte, error)
+
+	// Deserialize deserialized an object and returns the correct type of T.
 	Deserialize(data []byte) (*T, error)
+
+	// Format returns the format used for the serializer.
 	Format() string
 }
 
@@ -111,6 +116,7 @@ func (s JSONSerializer[T]) Deserialize(data []byte) (*T, error) {
 	return &zeroValue, fmt.Errorf("invalid serialization prefix %v", data[0])
 }
 
+// Format returns the format used for the serializer.
 func (s JSONSerializer[T]) Format() string {
 	return s.format
 }

coherence/v1client.go

@@ -843,19 +843,22 @@ func (m *streamManagerV1) putGenericRequest(ctx context.Context, reqType pb1.Nam
 	return unwrapBytes(result)
 }
 
+// BinaryKeyAndValue is an internal type exported only for serialization.
 type BinaryKeyAndValue struct {
 	Key    []byte
 	Value  []byte
 	Err    error
 	Cookie []byte
 }
 
+// BinaryKey is an internal type exported only for serialization.
 type BinaryKey struct {
 	Key    []byte
 	Err    error
 	Cookie []byte
 }
 
+// BinaryValue is an internal type exported only for serialization.
 type BinaryValue struct {
 	Value  []byte
 	Err    error

test/e2e/standalone/near_cache_test.go

@@ -13,7 +13,9 @@ import (
 	"github.com/oracle/coherence-go-client/v2/coherence/filters"
 	"github.com/oracle/coherence-go-client/v2/coherence/processors"
 	"github.com/oracle/coherence-go-client/v2/test/utils"
+	"log"
 	"math"
+	"strconv"
 	"testing"
 	"time"
 )
@@ -583,6 +585,63 @@ func TestNearCachePruneFactor(t *testing.T) {
 	g.Expect(coherence.GetNearCachePruneFactor[int, string](namedCache)).To(gomega.Equal(float32(0.8)))
 }
 
+// TestNearCacheComparison runs tests to compare near and normal cache and outputs size and memory usage.
+func TestNearCacheComparison(t *testing.T) {
+	g := gomega.NewWithT(t)
+	session, err := utils.GetSession()
+	g.Expect(err).ShouldNot(gomega.HaveOccurred())
+	defer session.Close()
+
+	const maxValues = 2_000
+
+	nearCacheOptions := &coherence.NearCacheOptions{HighUnits: maxValues * 2}
+	namedCache, err := coherence.GetNamedCache[string, string](session, "no-near-cache")
+	g.Expect(err).ShouldNot(gomega.HaveOccurred())
+
+	namedCacheNear, err := coherence.GetNamedCache[string, string](session, "near-cache", coherence.WithNearCache(nearCacheOptions))
+	g.Expect(err).ShouldNot(gomega.HaveOccurred())
+
+	g.Expect(namedCache.Clear(ctx)).ShouldNot(gomega.HaveOccurred())
+	g.Expect(namedCacheNear.Clear(ctx)).ShouldNot(gomega.HaveOccurred())
+
+	values := make(map[string]string, 0)
+
+	// populate the map
+	for i := 1; i <= maxValues; i++ {
+		kv := strconv.Itoa(i)
+		values[kv] = kv
+	}
+
+	log.Printf("Insert %v entries into caches", maxValues)
+
+	g.Expect(namedCache.PutAll(ctx, values)).ShouldNot(gomega.HaveOccurred())
+	g.Expect(namedCacheNear.PutAll(ctx, values)).ShouldNot(gomega.HaveOccurred())
+
+	log.Println("Start", maxValues, "gets on normal cache")
+	start := time.Now()
+	for i := 1; i <= maxValues; i++ {
+		kv := strconv.Itoa(i)
+		_, err = namedCache.Get(ctx, kv)
+		g.Expect(err).ShouldNot(gomega.HaveOccurred())
+	}
+
+	log.Printf("Time to get %v from normal cache is %v", maxValues, time.Since(start))
+
+	for j := 1; j <= 2; j++ {
+		log.Printf("Run %v of get %v gets on near cache", j, maxValues)
+		start = time.Now()
+		for i := 1; i <= maxValues; i++ {
+			kv := strconv.Itoa(i)
+			_, err = namedCacheNear.Get(ctx, kv)
+			g.Expect(err).ShouldNot(gomega.HaveOccurred())
+		}
+
+		log.Printf("Run: %v time to get %v from near cache is %v", j, maxValues, time.Since(start))
+	}
+
+	log.Println(namedCacheNear.GetNearCacheStats())
+}
+
 // TestInvalidNearCacheOptions runs tests to ensure that we can't create a named cache/map with invalid options.
 func TestInvalidNearCacheOptions(t *testing.T) {
 	var (