diff --git a/tools/cache/controller.go b/tools/cache/controller.go index b5d39252..73e7f8d7 100644 --- a/tools/cache/controller.go +++ b/tools/cache/controller.go @@ -79,6 +79,7 @@ type controller struct { clock clock.Clock } +// Controller is a generic controller framework. type Controller interface { Run(stopCh <-chan struct{}) HasSynced() bool @@ -149,7 +150,7 @@ func (c *controller) processLoop() { for { obj, err := c.config.Queue.Pop(PopProcessFunc(c.config.Process)) if err != nil { - if err == FIFOClosedError { + if err == ErrFIFOClosed { return } if c.config.RetryOnError { diff --git a/tools/cache/delta_fifo.go b/tools/cache/delta_fifo.go index f24eec25..db4519f2 100644 --- a/tools/cache/delta_fifo.go +++ b/tools/cache/delta_fifo.go @@ -160,7 +160,7 @@ func (f *DeltaFIFO) KeyOf(obj interface{}) (string, error) { return f.keyFunc(obj) } -// Return true if an Add/Update/Delete/AddIfNotPresent are called first, +// HasSynced returns true if an Add/Update/Delete/AddIfNotPresent are called first, // or an Update called first but the first batch of items inserted by Replace() has been popped func (f *DeltaFIFO) HasSynced() bool { f.lock.Lock() @@ -389,7 +389,7 @@ func (f *DeltaFIFO) GetByKey(key string) (item interface{}, exists bool, err err return d, exists, nil } -// Checks if the queue is closed +// IsClosed checks if the queue is closed func (f *DeltaFIFO) IsClosed() bool { f.closedLock.Lock() defer f.closedLock.Unlock() @@ -417,7 +417,7 @@ func (f *DeltaFIFO) Pop(process PopProcessFunc) (interface{}, error) { // When Close() is called, the f.closed is set and the condition is broadcasted. // Which causes this loop to continue and return from the Pop(). if f.IsClosed() { - return nil, FIFOClosedError + return nil, ErrFIFOClosed } f.cond.Wait() @@ -593,6 +593,7 @@ type KeyGetter interface { // DeltaType is the type of a change (addition, deletion, etc) type DeltaType string +// Change type definition const ( Added DeltaType = "Added" Updated DeltaType = "Updated" diff --git a/tools/cache/expiration_cache.go b/tools/cache/expiration_cache.go index 4b00544f..0fe77d63 100644 --- a/tools/cache/expiration_cache.go +++ b/tools/cache/expiration_cache.go @@ -55,7 +55,7 @@ type ExpirationPolicy interface { type TTLPolicy struct { // >0: Expire entries with an age > ttl // <=0: Don't expire any entry - Ttl time.Duration + TTL time.Duration // Clock used to calculate ttl expiration Clock clock.Clock @@ -64,7 +64,7 @@ type TTLPolicy struct { // IsExpired returns true if the given object is older than the ttl, or it can't // determine its age. func (p *TTLPolicy) IsExpired(obj *TimestampedEntry) bool { - return p.Ttl > 0 && p.Clock.Since(obj.Timestamp) > p.Ttl + return p.TTL > 0 && p.Clock.Since(obj.Timestamp) > p.TTL } // TimestampedEntry is the only type allowed in a ExpirationCache. diff --git a/tools/cache/expiration_cache_fakes.go b/tools/cache/expiration_cache_fakes.go index d61db3d5..33afd32c 100644 --- a/tools/cache/expiration_cache_fakes.go +++ b/tools/cache/expiration_cache_fakes.go @@ -33,16 +33,19 @@ func (c *fakeThreadSafeMap) Delete(key string) { } } +// FakeExpirationPolicy keeps the list for keys which never expires. type FakeExpirationPolicy struct { NeverExpire sets.String RetrieveKeyFunc KeyFunc } +// IsExpired used to check if object is expired. func (p *FakeExpirationPolicy) IsExpired(obj *TimestampedEntry) bool { key, _ := p.RetrieveKeyFunc(obj) return !p.NeverExpire.Has(key) } +// NewFakeExpirationStore creates a new instance for the ExpirationCache. func NewFakeExpirationStore(keyFunc KeyFunc, deletedKeys chan<- string, expirationPolicy ExpirationPolicy, cacheClock clock.Clock) Store { cacheStorage := NewThreadSafeStore(Indexers{}, Indices{}) return &ExpirationCache{ diff --git a/tools/cache/expiration_cache_test.go b/tools/cache/expiration_cache_test.go index 4c58a7f2..d5fa15c0 100644 --- a/tools/cache/expiration_cache_test.go +++ b/tools/cache/expiration_cache_test.go @@ -181,7 +181,7 @@ func TestTTLPolicy(t *testing.T) { t.Errorf("TTL Cache should expire entries older than ttl") } for _, ttl = range []time.Duration{0, -1} { - policy.Ttl = ttl + policy.TTL = ttl if policy.IsExpired(fakeTimestampedEntry) { t.Errorf("TTL policy should only expire entries when initialized with a ttl > 0") } diff --git a/tools/cache/fake_custom_store.go b/tools/cache/fake_custom_store.go index 62694b61..462d2266 100644 --- a/tools/cache/fake_custom_store.go +++ b/tools/cache/fake_custom_store.go @@ -16,7 +16,7 @@ limitations under the License. package cache -// FakeStore lets you define custom functions for store operations +// FakeCustomStore lets you define custom functions for store operations. type FakeCustomStore struct { AddFunc func(obj interface{}) error UpdateFunc func(obj interface{}) error diff --git a/tools/cache/fifo.go b/tools/cache/fifo.go index 508c5530..7a3bc3d3 100644 --- a/tools/cache/fifo.go +++ b/tools/cache/fifo.go @@ -34,7 +34,8 @@ type ErrRequeue struct { Err error } -var FIFOClosedError error = errors.New("DeltaFIFO: manipulating with closed queue") +// ErrFIFOClosed used when FIFO is closed +var ErrFIFOClosed = errors.New("DeltaFIFO: manipulating with closed queue") func (e ErrRequeue) Error() string { if e.Err == nil { @@ -66,7 +67,7 @@ type Queue interface { Close() } -// Helper function for popping from Queue. +// Pop is helper function for popping from Queue. // WARNING: Do NOT use this function in non-test code to avoid races // unless you really really really really know what you are doing. func Pop(queue Queue) interface{} { @@ -126,7 +127,7 @@ func (f *FIFO) Close() { f.cond.Broadcast() } -// Return true if an Add/Update/Delete/AddIfNotPresent are called first, +// HasSynced returns true if an Add/Update/Delete/AddIfNotPresent are called first, // or an Update called first but the first batch of items inserted by Replace() has been popped func (f *FIFO) HasSynced() bool { f.lock.Lock() @@ -242,7 +243,7 @@ func (f *FIFO) GetByKey(key string) (item interface{}, exists bool, err error) { return item, exists, nil } -// Checks if the queue is closed +// IsClosed checks if the queue is closed func (f *FIFO) IsClosed() bool { f.closedLock.Lock() defer f.closedLock.Unlock() @@ -267,7 +268,7 @@ func (f *FIFO) Pop(process PopProcessFunc) (interface{}, error) { // When Close() is called, the f.closed is set and the condition is broadcasted. // Which causes this loop to continue and return from the Pop(). if f.IsClosed() { - return nil, FIFOClosedError + return nil, ErrFIFOClosed } f.cond.Wait() diff --git a/tools/cache/heap.go b/tools/cache/heap.go index 7357ff97..e503a45a 100644 --- a/tools/cache/heap.go +++ b/tools/cache/heap.go @@ -28,7 +28,9 @@ const ( closedMsg = "heap is closed" ) +// LessFunc is used to compare two objects in the heap. type LessFunc func(interface{}, interface{}) bool + type heapItem struct { obj interface{} // The object which is stored in the heap. index int // The index of the object's key in the Heap.queue. @@ -158,7 +160,7 @@ func (h *Heap) Add(obj interface{}) error { return nil } -// Adds all the items in the list to the queue and then signals the condition +// BulkAdd adds all the items in the list to the queue and then signals the condition // variable. It is useful when the caller would like to add all of the items // to the queue before consumer starts processing them. func (h *Heap) BulkAdd(list []interface{}) error { @@ -249,11 +251,11 @@ func (h *Heap) Pop() (interface{}, error) { h.cond.Wait() } obj := heap.Pop(h.data) - if obj != nil { - return obj, nil - } else { + if obj == nil { return nil, fmt.Errorf("object was removed from heap data") } + + return obj, nil } // List returns a list of all the items. diff --git a/tools/cache/index.go b/tools/cache/index.go index 2a4bcbc4..9fa40683 100644 --- a/tools/cache/index.go +++ b/tools/cache/index.go @@ -75,6 +75,7 @@ func IndexFuncToKeyFuncAdapter(indexFunc IndexFunc) KeyFunc { } const ( + // NamespaceIndex is the lookup name for the most comment index function, which is to index by the namespace field. NamespaceIndex string = "namespace" ) diff --git a/tools/cache/listers.go b/tools/cache/listers.go index 311ff8c4..d649cd73 100644 --- a/tools/cache/listers.go +++ b/tools/cache/listers.go @@ -30,6 +30,7 @@ import ( // AppendFunc is used to add a matching item to whatever list the caller is using type AppendFunc func(interface{}) +// ListAll calls appendFn with each value retrieved from store which matches the selector. func ListAll(store Store, selector labels.Selector, appendFn AppendFunc) error { selectAll := selector.Empty() for _, m := range store.List() { @@ -50,6 +51,7 @@ func ListAll(store Store, selector labels.Selector, appendFn AppendFunc) error { return nil } +// ListAllByNamespace used to list items belongs to namespace from Indexer. func ListAllByNamespace(indexer Indexer, namespace string, selector labels.Selector, appendFn AppendFunc) error { selectAll := selector.Empty() if namespace == metav1.NamespaceAll { @@ -124,6 +126,7 @@ type GenericNamespaceLister interface { Get(name string) (runtime.Object, error) } +// NewGenericLister creates a new instance for the genericLister. func NewGenericLister(indexer Indexer, resource schema.GroupResource) GenericLister { return &genericLister{indexer: indexer, resource: resource} } diff --git a/tools/cache/mutation_cache.go b/tools/cache/mutation_cache.go index 4c6686e9..5d3245a6 100644 --- a/tools/cache/mutation_cache.go +++ b/tools/cache/mutation_cache.go @@ -42,6 +42,7 @@ type MutationCache interface { Mutation(interface{}) } +// ResourceVersionComparator is able to compare object versions. type ResourceVersionComparator interface { CompareResourceVersion(lhs, rhs runtime.Object) int } diff --git a/tools/cache/mutation_detector.go b/tools/cache/mutation_detector.go index f03738a1..9903b292 100644 --- a/tools/cache/mutation_detector.go +++ b/tools/cache/mutation_detector.go @@ -36,12 +36,14 @@ func init() { mutationDetectionEnabled, _ = strconv.ParseBool(os.Getenv("KUBE_CACHE_MUTATION_DETECTOR")) } -type CacheMutationDetector interface { +// MutationDetector is able to monitor if the object be modified outside. +type MutationDetector interface { AddObject(obj interface{}) Run(stopCh <-chan struct{}) } -func NewCacheMutationDetector(name string) CacheMutationDetector { +// NewCacheMutationDetector creates a new instance for the defaultCacheMutationDetector. +func NewCacheMutationDetector(name string) MutationDetector { if !mutationDetectionEnabled { return dummyMutationDetector{} } diff --git a/tools/cache/shared_informer.go b/tools/cache/shared_informer.go index 3271d959..a293b222 100644 --- a/tools/cache/shared_informer.go +++ b/tools/cache/shared_informer.go @@ -34,7 +34,7 @@ import ( // SharedInformer provides eventually consistent linkage of its // clients to the authoritative state of a given collection of // objects. An object is identified by its API group, kind/resource, -// namespace, and name. One SharedInfomer provides linkage to objects +// namespace, and name. One SharedInformer provides linkage to objects // of a particular API group and kind/resource. The linked object // collection of a SharedInformer may be further restricted to one // namespace and/or by label selector and/or field selector. @@ -44,7 +44,7 @@ import ( // A state is either "absent" or present with a ResourceVersion and // other appropriate content. // -// A SharedInformer maintains a local cache, exposed by Store(), of +// A SharedInformer maintains a local cache, exposed by GetStore(), of // the state of each relevant object. This cache is eventually // consistent with the authoritative state. This means that, unless // prevented by persistent communication problems, if ever a @@ -67,10 +67,10 @@ import ( // non-absent state for some object ID and the object is eventually // removed from the authoritative state then eventually the object is // removed from the local cache (unless the SharedInformer is stopped -// too soon, the authoritative state service emnds, or communication +// too soon, the authoritative state service ends, or communication // problems persistently thwart the desired result). // -// The keys in Store() are of the form namespace/name for namespaced +// The keys in GetStore() are of the form namespace/name for namespaced // objects, and are simply the name for non-namespaced objects. // // A client is identified here by a ResourceEventHandler. For every @@ -116,6 +116,7 @@ type SharedInformer interface { LastSyncResourceVersion() string } +// SharedIndexInformer provides add and get Indexers ability based on SharedInformer. type SharedIndexInformer interface { SharedInformer // AddIndexers add indexers to the informer before it starts. @@ -182,7 +183,7 @@ type sharedIndexInformer struct { controller Controller processor *sharedProcessor - cacheMutationDetector CacheMutationDetector + cacheMutationDetector MutationDetector // This block is tracked to handle late initialization of the controller listerWatcher ListerWatcher @@ -222,7 +223,7 @@ func (v *dummyController) HasSynced() bool { return v.informer.HasSynced() } -func (c *dummyController) LastSyncResourceVersion() string { +func (v *dummyController) LastSyncResourceVersion() string { return "" } diff --git a/tools/cache/thread_safe_store.go b/tools/cache/thread_safe_store.go index b74faa01..33e6239a 100644 --- a/tools/cache/thread_safe_store.go +++ b/tools/cache/thread_safe_store.go @@ -302,6 +302,7 @@ func (c *threadSafeMap) Resync() error { return nil } +// NewThreadSafeStore creates a new instance of ThreadSafeStore. func NewThreadSafeStore(indexers Indexers, indices Indices) ThreadSafeStore { return &threadSafeMap{ items: map[string]interface{}{}, diff --git a/tools/cache/undelta_store.go b/tools/cache/undelta_store.go index 117df46c..220845dd 100644 --- a/tools/cache/undelta_store.go +++ b/tools/cache/undelta_store.go @@ -31,6 +31,7 @@ type UndeltaStore struct { // Assert that it implements the Store interface. var _ Store = &UndeltaStore{} +// Add inserts an object into the store and sends complete state by calling PushFunc. // Note about thread safety. The Store implementation (cache.cache) uses a lock for all methods. // In the functions below, the lock gets released and reacquired betweend the {Add,Delete,etc} // and the List. So, the following can happen, resulting in two identical calls to PushFunc. @@ -41,7 +42,6 @@ var _ Store = &UndeltaStore{} // 3 Store.Add(b) // 4 Store.List() -> [a,b] // 5 Store.List() -> [a,b] - func (u *UndeltaStore) Add(obj interface{}) error { if err := u.Store.Add(obj); err != nil { return err @@ -50,6 +50,7 @@ func (u *UndeltaStore) Add(obj interface{}) error { return nil } +// Update sets an item in the cache to its updated state and sends complete state by calling PushFunc. func (u *UndeltaStore) Update(obj interface{}) error { if err := u.Store.Update(obj); err != nil { return err @@ -58,6 +59,7 @@ func (u *UndeltaStore) Update(obj interface{}) error { return nil } +// Delete removes an item from the cache and sends complete state by calling PushFunc. func (u *UndeltaStore) Delete(obj interface{}) error { if err := u.Store.Delete(obj); err != nil { return err @@ -66,6 +68,10 @@ func (u *UndeltaStore) Delete(obj interface{}) error { return nil } +// Replace will delete the contents of current store, using instead the given list. +// 'u' takes ownership of the list, you should not reference the list again +// after calling this function. +// The new contents complete state will be sent by calling PushFunc after replacement. func (u *UndeltaStore) Replace(list []interface{}, resourceVersion string) error { if err := u.Store.Replace(list, resourceVersion); err != nil { return err diff --git a/tools/cache/undelta_store_test.go b/tools/cache/undelta_store_test.go index 6316442e..b045ccfc 100644 --- a/tools/cache/undelta_store_test.go +++ b/tools/cache/undelta_store_test.go @@ -47,7 +47,7 @@ func TestUpdateCallsPush(t *testing.T) { } var got []interface{} - var callcount int = 0 + var callcount = 0 push := func(m []interface{}) { callcount++ got = m @@ -73,7 +73,7 @@ func TestDeleteCallsPush(t *testing.T) { } var got []interface{} - var callcount int = 0 + var callcount = 0 push := func(m []interface{}) { callcount++ got = m @@ -110,7 +110,7 @@ func TestReplaceCallsPush(t *testing.T) { } var got []interface{} - var callcount int = 0 + var callcount = 0 push := func(m []interface{}) { callcount++ got = m