Merge pull request #80565 from MikeSpreitzer/77636bis

Added info requested in review of #77636

Kubernetes-commit: 1f3dcb3745ba72644a401ecbb6f9366b6d8ee7eb

Godeps/Godeps.json

@@ -260,7 +260,7 @@
 		},
 		{
 			"ImportPath": "k8s.io/api",
-			"Rev": "077ce48e77da"
+			"Rev": "3ab596449d6f"
 		},
 		{
 			"ImportPath": "k8s.io/apimachinery",

go.mod

@@ -26,7 +26,7 @@ require (
 	golang.org/x/oauth2 v0.0.0-20190402181905-9f3314589c9a
 	golang.org/x/time v0.0.0-20161028155119-f51c12702a4d
 	google.golang.org/appengine v1.5.0 // indirect
-	k8s.io/api v0.0.0-20190808180749-077ce48e77da
+	k8s.io/api v0.0.0-20190809220925-3ab596449d6f
 	k8s.io/apimachinery v0.0.0-20190809020650-423f5d784010
 	k8s.io/klog v0.3.1
 	k8s.io/utils v0.0.0-20190801114015-581e00157fb1
@@ -40,6 +40,6 @@ replace (
 	golang.org/x/sys => golang.org/x/sys v0.0.0-20190209173611-3b5209105503
 	golang.org/x/text => golang.org/x/text v0.3.1-0.20181227161524-e6919f6577db
 	golang.org/x/tools => golang.org/x/tools v0.0.0-20190313210603-aa82965741a9
-	k8s.io/api => k8s.io/api v0.0.0-20190808180749-077ce48e77da
+	k8s.io/api => k8s.io/api v0.0.0-20190809220925-3ab596449d6f
 	k8s.io/apimachinery => k8s.io/apimachinery v0.0.0-20190809020650-423f5d784010
 )

go.sum

@@ -126,7 +126,7 @@ gopkg.in/yaml.v2 v2.2.1 h1:mUhvW9EsL+naU5Q3cakzfE91YhliOondGd6ZrsDBHQE=
 gopkg.in/yaml.v2 v2.2.1/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.2.2 h1:ZCJp+EgiOT7lHqUV2J862kp8Qj64Jo6az82+3Td9dZw=
 gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
-k8s.io/api v0.0.0-20190808180749-077ce48e77da/go.mod h1:irWZZ8fkUYB2+fwyvjN9QMt0m5/1PYsJc1eJElzGHeM=
+k8s.io/api v0.0.0-20190809220925-3ab596449d6f/go.mod h1:3Iy+myeAORNCLgjd/Xu9ebwN7Vh59Bw0vh9jhoX+V58=
 k8s.io/apimachinery v0.0.0-20190809020650-423f5d784010/go.mod h1:Waf/xTS2FGRrgXCkO5FP3XxTOWh0qLf2QhL1qFZZ/R8=
 k8s.io/gengo v0.0.0-20190128074634-0689ccc1d7d6/go.mod h1:ezvh/TsK7cY6rbqRK0oQQ8IAqLxYwwyPxAX1Pzy0ii0=
 k8s.io/klog v0.0.0-20181102134211-b9b56d5dfc92/go.mod h1:Gq+BEi5rUBO/HRz0bTSXDUcqjScdoY3a9IHpCEIOOfk=

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