Brushed up fairqueuing package

staging/src/k8s.io/apiserver/BUILD

@@ -47,7 +47,6 @@ filegroup(
         "//staging/src/k8s.io/apiserver/pkg/util/flowcontrol/metrics:all-srcs",
         "//staging/src/k8s.io/apiserver/pkg/util/flushwriter:all-srcs",
         "//staging/src/k8s.io/apiserver/pkg/util/openapi:all-srcs",
-        "//staging/src/k8s.io/apiserver/pkg/util/promise:all-srcs",
         "//staging/src/k8s.io/apiserver/pkg/util/proxy:all-srcs",
         "//staging/src/k8s.io/apiserver/pkg/util/shufflesharding:all-srcs",
         "//staging/src/k8s.io/apiserver/pkg/util/term:all-srcs",

staging/src/k8s.io/apiserver/pkg/util/flowcontrol/fairqueuing/BUILD

@@ -19,6 +19,7 @@ filegroup(
     name = "all-srcs",
     srcs = [
         ":package-srcs",
+        "//staging/src/k8s.io/apiserver/pkg/util/flowcontrol/fairqueuing/promise:all-srcs",
         "//staging/src/k8s.io/apiserver/pkg/util/flowcontrol/fairqueuing/queueset:all-srcs",
         "//staging/src/k8s.io/apiserver/pkg/util/flowcontrol/fairqueuing/testing:all-srcs",
     ],

staging/src/k8s.io/apiserver/pkg/util/flowcontrol/fairqueuing/interface.go

@@ -70,7 +70,9 @@ type QueueSetConfig struct {
 	Name string
 	// ConcurrencyLimit is the maximum number of requests of this QueueSet that may be executing at a time
 	ConcurrencyLimit int
-	// DesiredNumQueues is the number of queues that the API says should exist now
+	// DesiredNumQueues is the number of queues that the API says
+	// should exist now.  This may be zero, in which case
+	// QueueLengthLimit, HandSize, and RequestWaitLimit are ignored.
 	DesiredNumQueues int
 	// QueueLengthLimit is the maximum number of requests that may be waiting in a given queue at a time
 	QueueLengthLimit int

staging/src/k8s.io/apiserver/pkg/util/promise/BUILD → staging/src/k8s.io/apiserver/pkg/util/flowcontrol/fairqueuing/promise/BUILD

@@ -3,8 +3,8 @@ load("@io_bazel_rules_go//go:def.bzl", "go_library")
 go_library(
     name = "go_default_library",
     srcs = ["interface.go"],
-    importmap = "k8s.io/kubernetes/vendor/k8s.io/apiserver/pkg/util/promise",
-    importpath = "k8s.io/apiserver/pkg/util/promise",
+    importmap = "k8s.io/kubernetes/vendor/k8s.io/apiserver/pkg/util/flowcontrol/fairqueuing/promise",
+    importpath = "k8s.io/apiserver/pkg/util/flowcontrol/fairqueuing/promise",
     visibility = ["//visibility:public"],
 )
 
@@ -19,7 +19,7 @@ filegroup(
     name = "all-srcs",
     srcs = [
         ":package-srcs",
-        "//staging/src/k8s.io/apiserver/pkg/util/promise/lockingpromise:all-srcs",
+        "//staging/src/k8s.io/apiserver/pkg/util/flowcontrol/fairqueuing/promise/lockingpromise:all-srcs",
     ],
     tags = ["automanaged"],
     visibility = ["//visibility:public"],

staging/src/k8s.io/apiserver/pkg/util/promise/lockingpromise/BUILD → staging/src/k8s.io/apiserver/pkg/util/flowcontrol/fairqueuing/promise/lockingpromise/BUILD

@@ -3,12 +3,12 @@ load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test")
 go_library(
     name = "go_default_library",
     srcs = ["lockingpromise.go"],
-    importmap = "k8s.io/kubernetes/vendor/k8s.io/apiserver/pkg/util/promise/lockingpromise",
-    importpath = "k8s.io/apiserver/pkg/util/promise/lockingpromise",
+    importmap = "k8s.io/kubernetes/vendor/k8s.io/apiserver/pkg/util/flowcontrol/fairqueuing/promise/lockingpromise",
+    importpath = "k8s.io/apiserver/pkg/util/flowcontrol/fairqueuing/promise/lockingpromise",
     visibility = ["//visibility:public"],
     deps = [
         "//staging/src/k8s.io/apiserver/pkg/util/flowcontrol/counter:go_default_library",
-        "//staging/src/k8s.io/apiserver/pkg/util/promise:go_default_library",
+        "//staging/src/k8s.io/apiserver/pkg/util/flowcontrol/fairqueuing/promise:go_default_library",
     ],
 )
 

staging/src/k8s.io/apiserver/pkg/util/promise/lockingpromise/lockingpromise.go → staging/src/k8s.io/apiserver/pkg/util/flowcontrol/fairqueuing/promise/lockingpromise/lockingpromise.go

@@ -20,7 +20,7 @@ import (
 	"sync"
 
 	"k8s.io/apiserver/pkg/util/flowcontrol/counter"
-	"k8s.io/apiserver/pkg/util/promise"
+	"k8s.io/apiserver/pkg/util/flowcontrol/fairqueuing/promise"
 )
 
 // lockingPromise implements LockingMutable based on a condition

staging/src/k8s.io/apiserver/pkg/util/flowcontrol/fairqueuing/queueset/BUILD

@@ -15,9 +15,9 @@ go_library(
         "//staging/src/k8s.io/apimachinery/pkg/util/runtime:go_default_library",
         "//staging/src/k8s.io/apiserver/pkg/util/flowcontrol/counter:go_default_library",
         "//staging/src/k8s.io/apiserver/pkg/util/flowcontrol/fairqueuing:go_default_library",
+        "//staging/src/k8s.io/apiserver/pkg/util/flowcontrol/fairqueuing/promise:go_default_library",
+        "//staging/src/k8s.io/apiserver/pkg/util/flowcontrol/fairqueuing/promise/lockingpromise:go_default_library",
         "//staging/src/k8s.io/apiserver/pkg/util/flowcontrol/metrics:go_default_library",
-        "//staging/src/k8s.io/apiserver/pkg/util/promise:go_default_library",
-        "//staging/src/k8s.io/apiserver/pkg/util/promise/lockingpromise:go_default_library",
         "//staging/src/k8s.io/apiserver/pkg/util/shufflesharding:go_default_library",
         "//vendor/github.com/pkg/errors:go_default_library",
         "//vendor/k8s.io/klog:go_default_library",

staging/src/k8s.io/apiserver/pkg/util/flowcontrol/fairqueuing/queueset/doc.go

@@ -14,33 +14,31 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-package queueset
-
-// This package implements a technique called "fair queuing for server
-// requests".  One QueueSet is a set of queues operating according to
-// this technique.
-
+// Package queueset implements a technique called "fair queuing for
+// server requests".  One QueueSet is a set of queues operating
+// according to this technique.
+//
 // Fair queuing for server requests is inspired by the fair queuing
 // technique from the world of networking.  You can find a good paper
 // on that at https://dl.acm.org/citation.cfm?doid=75247.75248 or
 // http://people.csail.mit.edu/imcgraw/links/research/pubs/networks/WFQ.pdf
 // and there is an implementation outline in the Wikipedia article at
 // https://en.wikipedia.org/wiki/Fair_queuing .
-
+//
 // Fair queuing for server requests differs from traditional fair
-// queuing in three ways: (1) we are dispatching requests to be
-// executed within a process rather than transmitting packets on a
-// network link, (2) multiple requests can be executing at once, and
-// (3) the service time (execution duration) is not known until the
-// execution completes.
-
+// queuing in three ways: (1) we are dispatching application layer
+// requests to a server rather than transmitting packets on a network
+// link, (2) multiple requests can be executing at once, and (3) the
+// service time (execution duration) is not known until the execution
+// completes.
+//
 // The first two differences can easily be handled by straightforward
 // adaptation of the concept called "R(t)" in the original paper and
 // "virtual time" in the implementation outline. In that
 // implementation outline, the notation now() is used to mean reading
 // the virtual clock. In the original paper’s terms, "R(t)" is the
-// number of "rounds" that have been completed at real time t, where a
-// round consists of virtually transmitting one bit from every
+// number of "rounds" that have been completed at real time t ---
+// where a round consists of virtually transmitting one bit from every
 // non-empty queue in the router (regardless of which queue holds the
 // packet that is really being transmitted at the moment); in this
 // conception, a packet is considered to be "in" its queue until the
@@ -55,12 +53,12 @@ package queueset
 // respect to t is
 //
 //                 1 / NEQ(t) .
-
+//
 // To generalize from transmitting one packet at a time to executing C
 // requests at a time, that derivative becomes
 //
 //                C / NEQ(t) .
-
+//
 // However, sometimes there are fewer than C requests available to
 // execute.  For a given queue "q", let us also write "reqs(q, t)" for
 // the number of requests of that queue that are executing at that
@@ -79,25 +77,25 @@ package queueset
 // real nanosecond). Where the networking implementation outline adds
 // packet size to a virtual time, in our version this corresponds to
 // adding a service time (i.e., duration) to virtual time.
-
+//
 // The third difference is handled by modifying the algorithm to
 // dispatch based on an initial guess at the request’s service time
 // (duration) and then make the corresponding adjustments once the
 // request’s actual service time is known. This is similar, although
 // not exactly isomorphic, to the original paper’s adjustment by
-// `$delta` for the sake of promptness.
-
+// `$\delta$` for the sake of promptness.
+//
 // For implementation simplicity (see below), let us use the same
 // initial service time guess for every request; call that duration
 // G. A good choice might be the service time limit (1
 // minute). Different guesses will give slightly different dynamics,
 // but any positive number can be used for G without ruining the
 // long-term behavior.
-
+//
 // As in ordinary fair queuing, there is a bound on divergence from
 // the ideal. In plain fair queuing the bound is one packet; in our
 // version it is C requests.
-
+//
 // To support efficiently making the necessary adjustments once a
 // request’s actual service time is known, the virtual finish time of
 // a request and the last virtual finish time of a queue are not
@@ -118,3 +116,5 @@ package queueset
 // queue’s virtual start time is advanced by G. When a request
 // finishes being served, and the actual service time was S, the
 // queue’s virtual start time is decremented by G - S.
+//
+package queueset