From 1dd778153e11ab5dc3ba25cd57054dc01407d0c2 Mon Sep 17 00:00:00 2001 From: Mike Spreitzer Date: Thu, 9 May 2019 01:34:02 -0400 Subject: [PATCH] Made the comment on SharedInformer give a complete description This comment formerly contained only a contrast with "standard informer", but there is no longer such a thing so the comment lacked much important information. Kubernetes-commit: 121e4741463043eac188bb4eed51f07122262d69 --- tools/cache/shared_informer.go | 80 ++++++++++++++++++++++++++++------ 1 file changed, 66 insertions(+), 14 deletions(-) diff --git a/tools/cache/shared_informer.go b/tools/cache/shared_informer.go index 9715d344..d76ade8e 100644 --- a/tools/cache/shared_informer.go +++ b/tools/cache/shared_informer.go @@ -31,31 +31,83 @@ import ( "k8s.io/klog" ) -// SharedInformer has a shared data cache and is capable of distributing notifications for changes -// to the cache to multiple listeners who registered via AddEventHandler. If you use this, there is -// one behavior change compared to a standard Informer. When you receive a notification, the cache -// will be AT LEAST as fresh as the notification, but it MAY be more fresh. You should NOT depend -// on the contents of the cache exactly matching the notification you've received in handler -// functions. If there was a create, followed by a delete, the cache may NOT have your item. This -// has advantages over the broadcaster since it allows us to share a common cache across many -// controllers. Extending the broadcaster would have required us keep duplicate caches for each -// watch. +// 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 +// 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. +// +// The authoritative state of an object is what apiservers provide +// access to, and an object goes through a strict sequence of states. +// A state is either "absent" or present with a ResourceVersion and +// other appropriate content. +// +// A SharedInformer maintains a local cache, exposed by Store(), 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 +// particular object ID X is authoritatively associated with a state S +// then for every SharedInformer I whose collection includes (X, S) +// eventually either (1) I's cache associates X with S or a later +// state of X, (2) I is stopped, or (3) the authoritative state +// service for X terminates. To be formally complete, we say that the +// absent state meets any restriction by label selector or field +// selector. +// +// As a simple example, if a collection of objects is henceforeth +// unchanging and a SharedInformer is created that links to that +// collection then that SharedInformer's cache eventually holds an +// exact copy of that collection (unless it is stopped too soon, the +// authoritative state service ends, or communication problems between +// the two persistently thwart achievement). +// +// As another simple example, if the local cache ever holds a +// 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 +// problems persistently thwart the desired result). +// +// The keys in Store() 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 +// update to the SharedInformer's local cache and for every client, +// eventually either the SharedInformer is stopped or the client is +// notified of the update. These notifications happen after the +// corresponding cache update and, in the case of a +// SharedIndexInformer, after the corresponding index updates. It is +// possible that additional cache and index updates happen before such +// a prescribed notification. For a given SharedInformer and client, +// all notifications are delivered sequentially. For a given +// SharedInformer, client, and object ID, the notifications are +// delivered in order. +// +// A delete notification exposes the last locally known non-absent +// state, except that its ResourceVersion is replaced with a +// ResourceVersion in which the object is actually absent. type SharedInformer interface { // AddEventHandler adds an event handler to the shared informer using the shared informer's resync // period. Events to a single handler are delivered sequentially, but there is no coordination // between different handlers. AddEventHandler(handler ResourceEventHandler) - // AddEventHandlerWithResyncPeriod adds an event handler to the shared informer using the - // specified resync period. Events to a single handler are delivered sequentially, but there is - // no coordination between different handlers. + // AddEventHandlerWithResyncPeriod adds an event handler to the + // shared informer using the specified resync period. The resync + // operation consists of delivering to the handler a create + // notification for every object in the informer's local cache; it + // does not add any interactions with the authoritative storage. AddEventHandlerWithResyncPeriod(handler ResourceEventHandler, resyncPeriod time.Duration) - // GetStore returns the Store. + // GetStore returns the informer's local cache as a Store. GetStore() Store // GetController gives back a synthetic interface that "votes" to start the informer GetController() Controller // Run starts the shared informer, which will be stopped when stopCh is closed. Run(stopCh <-chan struct{}) - // HasSynced returns true if the shared informer's store has synced. + // HasSynced returns true if the shared informer's store has been + // informed by at least one full LIST of the authoritative state + // of the informer's object collection. This is unrelated to "resync". HasSynced() bool // LastSyncResourceVersion is the resource version observed when last synced with the underlying // store. The value returned is not synchronized with access to the underlying store and is not