Organize code and document allocator interface better

Author: jpbetz

value/allocator.go

@@ -0,0 +1,216 @@
+/*
+Copyright 2020 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package value
+
+// Allocator provides a value object allocation strategy.
+// Value objects can be allocated by passing an allocator to the "Using"
+// receiver functions on the value interfaces, e.g. Map.ZipUsing(allocator, ...).
+// Value objects returned from "Using" functions should be given back to the allocator
+// once longer needed by calling Allocator.Free(Value).
+type Allocator interface {
+	// Free gives the allocator back any value objects returned by the "Using"
+	// receiver functions on the value interfaces.
+	// interface{} may be any of: Value, Map, List or Range.
+	Free(interface{})
+
+	// The unexported functions are for "Using" receiver functions of the value types
+	// to request what they need from the allocator.
+	allocValueUnstructured() *valueUnstructured
+	allocListUnstructuredRange() *listUnstructuredRange
+	allocValueReflect() *valueReflect
+	allocMapReflect() *mapReflect
+	allocStructReflect() *structReflect
+	allocListReflect() *listReflect
+	allocListReflectRange() *listReflectRange
+}
+
+// HeapAllocator simply allocates objects to the heap. It is the default
+// allocator used receiver functions on the value interfaces that do not accept
+// an allocator and should be used whenever allocating objects that will not
+// be given back to an allocator by calling Allocator.Free(Value).
+var HeapAllocator = &heapAllocator{}
+
+type heapAllocator struct{}
+
+func (p *heapAllocator) allocValueUnstructured() *valueUnstructured {
+	return &valueUnstructured{}
+}
+
+func (p *heapAllocator) allocListUnstructuredRange() *listUnstructuredRange {
+	return &listUnstructuredRange{vv: &valueUnstructured{}}
+}
+
+func (p *heapAllocator) allocValueReflect() *valueReflect {
+	return &valueReflect{}
+}
+
+func (p *heapAllocator) allocStructReflect() *structReflect {
+	return &structReflect{}
+}
+
+func (p *heapAllocator) allocMapReflect() *mapReflect {
+	return &mapReflect{}
+}
+
+func (p *heapAllocator) allocListReflect() *listReflect {
+	return &listReflect{}
+}
+
+func (p *heapAllocator) allocListReflectRange() *listReflectRange {
+	return &listReflectRange{vr: &valueReflect{}}
+}
+
+func (p *heapAllocator) Free(_ interface{}) {}
+
+// NewFreelistAllocator create freelists based allocator.
+// This allocator provides fast allocation and freeing of short lived value objects.
+//
+// The freelists are bounded in size by freelistMaxSize. If more than this amount of value objects is
+// allocated at once, the excess will be returned to the heap for garbage collection when freed.
+//
+// This allocator is unsafe and must not be accessed concurrently by goroutines.
+//
+// This allocator works well for traversal of value data trees. Typical usage is to acquire
+// a freelist at the beginning of the traversal and use it through out
+// for all temporary value access.
+func NewFreelistAllocator() Allocator {
+	return &freelist{}
+}
+
+// Bound memory usage of freelists. This prevents the processing of very large lists from leaking memory.
+// This limit is large enough for endpoints objects containing 1000 IP address entries. Freed objects
+// that don't fit into the freelist are orphaned on the heap to be garbage collected.
+const freelistMaxSize = 1000
+
+type freelist struct {
+	spareUnstructured          []*valueUnstructured
+	spareListUnstructuredRange []*listUnstructuredRange
+	spareReflect               []*valueReflect
+	spareMapReflect            []*mapReflect
+	spareStructReflect         []*structReflect
+	spareListReflect           []*listReflect
+	spareListReflectRange      []*listReflectRange
+}
+
+func (w *freelist) Free(value interface{}) {
+	switch v := value.(type) {
+	case *valueUnstructured:
+		v.Value = nil // don't hold references to unstructured objects
+		if len(w.spareUnstructured) < freelistMaxSize {
+			w.spareUnstructured = append(w.spareUnstructured, v)
+		}
+	case *listUnstructuredRange:
+		v.vv.Value = nil // don't hold references to unstructured objects
+		if len(w.spareListUnstructuredRange) < freelistMaxSize {
+			w.spareListUnstructuredRange = append(w.spareListUnstructuredRange, v)
+		}
+	case *valueReflect:
+		v.ParentMapKey = nil
+		v.ParentMap = nil
+		if len(w.spareReflect) < freelistMaxSize {
+			w.spareReflect = append(w.spareReflect, v)
+		}
+	case *mapReflect:
+		if len(w.spareMapReflect) < freelistMaxSize {
+			w.spareMapReflect = append(w.spareMapReflect, v)
+		}
+	case *structReflect:
+		if len(w.spareStructReflect) < freelistMaxSize {
+			w.spareStructReflect = append(w.spareStructReflect, v)
+		}
+	case *listReflect:
+		if len(w.spareListReflect) < freelistMaxSize {
+			w.spareListReflect = append(w.spareListReflect, v)
+		}
+	case *listReflectRange:
+		v.vr.ParentMapKey = nil
+		v.vr.ParentMap = nil
+		if len(w.spareListReflectRange) < freelistMaxSize {
+			w.spareListReflectRange = append(w.spareListReflectRange, v)
+		}
+	}
+}
+
+func (w *freelist) allocValueUnstructured() *valueUnstructured {
+	var w2 *valueUnstructured
+	if n := len(w.spareUnstructured); n > 0 {
+		w2, w.spareUnstructured = (w.spareUnstructured)[n-1], (w.spareUnstructured)[:n-1]
+	} else {
+		w2 = &valueUnstructured{}
+	}
+	return w2
+}
+
+func (w *freelist) allocListUnstructuredRange() *listUnstructuredRange {
+	var w2 *listUnstructuredRange
+	if n := len(w.spareListUnstructuredRange); n > 0 {
+		w2, w.spareListUnstructuredRange = (w.spareListUnstructuredRange)[n-1], (w.spareListUnstructuredRange)[:n-1]
+	} else {
+		w2 = &listUnstructuredRange{vv: &valueUnstructured{}}
+	}
+	return w2
+}
+
+func (w *freelist) allocValueReflect() *valueReflect {
+	var w2 *valueReflect
+	if n := len(w.spareReflect); n > 0 {
+		w2, w.spareReflect = (w.spareReflect)[n-1], (w.spareReflect)[:n-1]
+	} else {
+		w2 = &valueReflect{}
+	}
+	return w2
+}
+
+func (w *freelist) allocStructReflect() *structReflect {
+	var w2 *structReflect
+	if n := len(w.spareStructReflect); n > 0 {
+		w2, w.spareStructReflect = (w.spareStructReflect)[n-1], (w.spareStructReflect)[:n-1]
+	} else {
+		w2 = &structReflect{}
+	}
+	return w2
+}
+
+func (w *freelist) allocMapReflect() *mapReflect {
+	var w2 *mapReflect
+	if n := len(w.spareMapReflect); n > 0 {
+		w2, w.spareMapReflect = (w.spareMapReflect)[n-1], (w.spareMapReflect)[:n-1]
+	} else {
+		w2 = &mapReflect{}
+	}
+	return w2
+}
+
+func (w *freelist) allocListReflect() *listReflect {
+	var w2 *listReflect
+	if n := len(w.spareListReflect); n > 0 {
+		w2, w.spareListReflect = (w.spareListReflect)[n-1], (w.spareListReflect)[:n-1]
+	} else {
+		w2 = &listReflect{}
+	}
+	return w2
+}
+
+func (w *freelist) allocListReflectRange() *listReflectRange {
+	var w2 *listReflectRange
+	if n := len(w.spareListReflectRange); n > 0 {
+		w2, w.spareListReflectRange = (w.spareListReflectRange)[n-1], (w.spareListReflectRange)[:n-1]
+	} else {
+		w2 = &listReflectRange{vr: &valueReflect{}}
+	}
+	return w2
+}