Added info requested in review of #77636, and more

Added definition of "collection states" and noted that informer cache
queries are answered against these.

Also added an explicit note that the concept of object identity used
in the contract here does _not_ include ObjectMeta.UID.

Also updated the description of the notifications received by a
client, to account for the fact that a client can be added after the
informer starts running.

Added references to `MetaNamespaceKeyFunc` and
`SplitMetaNamespaceKey`.

Noted that a client must process each notification promptly and added
a referral to workqueue.

Made a couple other minor clarifications and corrections.

Kubernetes-commit: 848301e11a8558f6a90e2fada870a91baace812a

tools/cache/shared_informer.go

@@ -34,34 +34,49 @@ 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 SharedInformer provides linkage to objects
+// namespace, and name; the `ObjectMeta.UID` is not part of an
-// of a particular API group and kind/resource.  The linked object
+// object's ID as far as this contract is concerned.  One
-// collection of a SharedInformer may be further restricted to one
+// SharedInformer provides linkage to objects of a particular API
-// namespace and/or by label selector and/or field selector.
+// 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
+// An object state is either "absent" or present with a
-// other appropriate content.
+// ResourceVersion and other appropriate content.
 //
-// A SharedInformer maintains a local cache, exposed by GetStore(), of
+// A SharedInformer gets object states from apiservers using a
-// the state of each relevant object.  This cache is eventually
+// sequence of LIST and WATCH operations.  Through this sequence the
-// consistent with the authoritative state.  This means that, unless
+// apiservers provide a sequence of "collection states" to the
-// prevented by persistent communication problems, if ever a
+// informer, where each collection state defines the state of every
-// particular object ID X is authoritatively associated with a state S
+// object of the collection.  No promise --- beyond what is implied by
-// then for every SharedInformer I whose collection includes (X, S)
+// other remarks here --- is made about how one informer's sequence of
-// eventually either (1) I's cache associates X with S or a later
+// collection states relates to a different informer's sequence of
-// state of X, (2) I is stopped, or (3) the authoritative state
+// collection states.
-// service for X terminates.  To be formally complete, we say that the
+//
-// absent state meets any restriction by label selector or field
+// A SharedInformer maintains a local cache, exposed by GetStore() and
-// selector.
+// by GetIndexer() in the case of an indexed informer, 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.
+//
+// The local cache starts out empty, and gets populated and updated
+// during `Run()`.
 //
 // As a simple example, if a collection of objects is henceforeth
-// unchanging and a SharedInformer is created that links to that
+// unchanging, a SharedInformer is created that links to that
-// collection then that SharedInformer's cache eventually holds an
+// collection, and that SharedInformer is `Run()` then that
-// exact copy of that collection (unless it is stopped too soon, the
+// SharedInformer's cache eventually holds an exact copy of that
-// authoritative state service ends, or communication problems between
+// collection (unless it is stopped too soon, the authoritative state
-// the two persistently thwart achievement).
+// 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
@@ -70,20 +85,39 @@ import (
 // too soon, the authoritative state service ends, or communication
 // problems persistently thwart the desired result).
 //
-// The keys in GetStore() are of the form namespace/name for namespaced
+// The keys in the Store are of the form namespace/name for namespaced
 // objects, and are simply the name for non-namespaced objects.
+// Clients can use `MetaNamespaceKeyFunc(obj)` to extract the key for
+// a given object, and `SplitMetaNamespaceKey(key)` to split a key
+// into its constituent parts.
 //
 // A client is identified here by a ResourceEventHandler.  For every
-// update to the SharedInformer's local cache and for every client,
+// update to the SharedInformer's local cache and for every client
-// eventually either the SharedInformer is stopped or the client is
+// added before `Run()`, eventually either the SharedInformer is
-// notified of the update.  These notifications happen after the
+// stopped or the client is notified of the update.  A client added
-// corresponding cache update and, in the case of a
+// after `Run()` starts gets a startup batch of notifications of
-// SharedIndexInformer, after the corresponding index updates.  It is
+// additions of the object existing in the cache at the time that
-// possible that additional cache and index updates happen before such
+// client was added; also, for every update to the SharedInformer's
-// a prescribed notification.  For a given SharedInformer and client,
+// local cache after that client was added, eventually either the
-// all notifications are delivered sequentially.  For a given
+// SharedInformer is stopped or that client is notified of that
-// SharedInformer, client, and object ID, the notifications are
+// update.  Client notifications happen after the corresponding cache
-// delivered in order.
+// 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, the notifications are
+// delivered sequentially.  For a given SharedInformer, client, and
+// object ID, the notifications are delivered in order.
+//
+// A client must process each notification promptly; a SharedInformer
+// is not engineered to deal well with a large backlog of
+// notifications to deliver.  Lengthy processing should be passed off
+// to something else, for example through a
+// `client-go/util/workqueue`.
+//
+// Each query to an informer's local cache --- whether a single-object
+// lookup, a list operation, or a use of one of its indices --- is
+// answered entirely from one of the collection states received by
+// that informer.
 //
 // A delete notification exposes the last locally known non-absent
 // state, except that its ResourceVersion is replaced with a