Change:
<!-- Please use this template while reporting a bug and provide as much info as possible. Not doing so may result in your bug not being addressed in a timely manner. Thanks! If the matter is security related, please disclose it privately via --What happened: As a developer, I had important questions about SharedInformer that I could not answer from the comments on it. Colleagues also have questions. The comments on SharedInformer mainly contain a contrast with "standard Informer" --- but there no longer is such a thing. So most of the important facts about SharedInformer are not documented in the comments. What you expected to happen: I expected to be able to understand the contract between a SharedInformer and its clients by reading the comments on that interface. How to reproduce it (as minimally and precisely as possible): Anything else we need to know?: Environment: Kubernetes version (use ): Cloud provider or hardware configuration: OS (e.g: ): Kernel (e.g. ): Install tools: Network plugin and version (if this is a network-related bug): Others:

Discussion:
"k8s.io/klog" ) <del> // 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. </del> <ins> // 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. </ins> 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) <del> // 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. </del> <ins> // 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. </ins> AddEventHandlerWithResyncPeriod(handler ResourceEventHandler, resyncPeriod time.Duration) <del> // GetStore returns the Store. </del> <ins> // GetStore returns the informer's local cache as a Store. </ins> 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{}) <del> // HasSynced returns true if the shared informer's store has synced. </del> <ins> // 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". </ins> 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