update docstring

pkg/scheduler/queue/tree_queue_algo_querier_worker_queue_priority.go

@@ -12,25 +12,25 @@ package queue
 // in situations of high latency on a query component, the one slow query component will still grow asymptotically
 // to dominate the utilization the querier-worker connections, as measured by inflight query processing time.
 //
-// There are four possible query components: "ingester", "store-gateway", "ingester-and-store-gateway", and "unknown".
-// With all four queue nodes active, approximately 1 / 4 of the querier-workers are prioritized to each queue node.
-// Assuming the above query-component node order, a querier-worker ID which is evenly divisible by 4
+// There are 4 possible query components: "ingester", "store-gateway", "ingester-and-store-gateway", and "unknown".
+// With all 4 queue nodes active, approximately 1 / 4 of the querier-workers are prioritized to each queue node.
+// Assuming the above query-component nodeOrder, a querier-worker ID which is evenly divisible by 4
 // always first attempts to dequeue a query from the "ingester" queue node at index 0 in the nodeOrder.
 //
 // This algorithm requires a minimum of 4 querier-workers per querier to prevent queue starvation.
 // The minimum is enforced in the queriers by overriding -querier.max-concurrent if necessary.
 //
-// It is not required that the number of querier-workers be divisible by four; this algorithm assumes that
-// the MultiQueuingAlgorithmTreeQueue always deletes empty nodes recursively after a dequeue operation.
-// and if a new request is enqueued for a previously-deleted paths, nodes are re-created.
-// This has two implications for the distribution of workers across queue nodes:
+// MultiQueuingAlgorithmTreeQueue always deletes empty leaf nodes and nodes with no children after a dequeue operation,
+// and only recreates the queue nodes when a new query request is enqueued which requires that path through the tree.
+// QuerierWorkerQueuePriorityAlgo responds by removing or re-adding the query component nodes to the nodeOrder.
+// Therefore:
 //  1. The modulo operation may modulo the worker ID by 1, 2, 3, or 4 depending on the number of node types
-//     currently present in the node order, which can change which node a worker ID is prioritized for.
-//  2. The node order changes as queues are deleted and re-created, so the worker ID-to-node mapping changes
+//     currently present in the nodeOrder, which can change which node a worker ID is prioritized for.
+//  2. The nodeOrder changes as queues are deleted and re-created, so the worker ID-to-node mapping changes
 //     as the random enqueue order places query component nodes in different positions in the order.
 //
 // These changes in nodeOrder guarantee that when the number of querier-workers is not evenly divisible
-// by the number of query component nodes, through the randomized changes in node order over time, the workers
+// by the number of query component nodes, through the randomized changes in nodeOrder over time, the workers
 // are more evenly distributed across query component nodes than if length and order of the nodes were fixed.
 //
 // A given worker ID is prioritized to *start* at a given queue node, but is not assigned strictly to that node.
@@ -43,8 +43,7 @@ package queue
 // tree. If shuffle-sharding is enabled, a querier-worker that prioritizes ingester-only queries may not find
 // ingester-only queries for any tenant it is assigned to, and move on to the next query component subtree. E.g.:
 //
-//  1. The QuerierWorkerQueuePriorityAlgo has node order:
-//     ["ingester", "store-gateway", "ingester-and-store-gateway", "unknown"].
+//  1. This algorithm has nodeOrder: ["ingester", "store-gateway", "ingester-and-store-gateway", "unknown"].
 //
 //  2. A querier-worker with workerID 0 requests to dequeue; it prioritizes the "ingester" queue node.
 //