admission: add local token reservation to SQLCPUHandle

[wenyihu6]

Part of: #166749
Epic: none
Release note: None

---

admission: extract reportCPU helper

This commit extracts the cumulative CPU counter update into a
standalone reportCPU helper on SQLCPUHandle.
reportAndAcquireConsumedCPU now delegates to reportCPU for the
counter update before proceeding with CTT WorkQueue admission.

Epic: none
Release note: None

Co-Authored-By: roachdev-claude roachdev-claude-bot@cockroachlabs.com

---

admission: add local token reservation to SQLCPUHandle

Each measureAndAdmit call on a SQL goroutine calls WorkQueue.Admit,
acquiring the WorkQueue mutex on every checkpoint (~1024 rows). For
statements with many goroutines, this creates contention on
WorkQueue.mu.

This change introduces a local token reservation in SQLCPUHandle.
When a goroutine consumes CPU, it first attempts to deduct from the
reservation via a lock-free CAS. If the reservation covers the full
deficit, the goroutine returns immediately without calling Admit.
When the reservation is insufficient, the goroutine enters the slow
path: it acquires a turn via a capacity-1 channel (serializing blocking
Admit calls across goroutines), calls Admit for the deficit plus a
buffer (see refillHeuristic), and stores the buffer in the
reservation for future fast-path deductions.

Epic: none
Release note: None

Co-Authored-By: roachdev-claude roachdev-claude-bot@cockroachlabs.com

[trunk-io]

😎 Merged directly without going through the merge queue, as the queue was empty and the PR was up to date with the target branch - details.

[cockroach-teamcity]

This change is 

[tbg]

@tbg reviewed 4 files and all commit messages, and made 1 comment.
Reviewable status: complete! 1 of 0 LGTMs obtained (waiting on sumeerbhola).

[wenyihu6]

Gonna go ahead and merge this. Lmk if you have comments, and I will address in a follow up @sumeerbhola.

/trunk merge

[wenyihu6]

/trunk cancel

[sumeerbhola]

@sumeerbhola reviewed 2 files and made 5 comments.
Reviewable status: complete! 2 of 0 LGTMs obtained (waiting on wenyihu6).

---

pkg/util/admission/sql_cpu_handle.go line 230 at r3 (raw file):

// cpuTimeTokenEstimator (see callerSetRequestedCount in Admit). This is
// required for SQL CPU admission, which already knows the exact CPU consumed
// from grunning and does not need/want estimation.

should this say
// REQUIRES: reqCount > 0

---

pkg/util/admission/sql_cpu_handle.go line 270 at r3 (raw file):

//
// When SQLCPUHandle is closed, any remaining reservation should be
// returned via AdmittedSQLWorkDone. That said, small token leaks are

If this code is never leaking tokens, it seems unnecessary to have multiple sentences about leaks.
Or at least we should make it clear to the reader that this code doesn't leak, even though small leaks are harmless.

---

pkg/util/admission/sql_cpu_handle.go line 328 at r3 (raw file):

	resp, err := h.wq.Admit(ctx, h.constructWorkInfo(h.refillHeuristic(remaining), false /*noWait*/))
	if err != nil {
		return err

error will only happen on context cancellation, iirc. Please confirm.

So this should be handled also by accounting for the deficit without blocking.

---

pkg/util/admission/sql_cpu_handle.go line 347 at r3 (raw file):

		// Close already ran and drained reservation. Return the buffer
		// directly.
		if closed && buffer > 0 {

This buffer > 0 could be hoisted before calling the preceding closure.

[wenyihu6]

TFTRs!

/trunk merge

@wenyihu6 made 5 comments.
Reviewable status: complete! 0 of 0 LGTMs obtained (and 2 stale) (waiting on sumeerbhola and tbg).

---

pkg/util/admission/sql_cpu_handle.go line 230 at r3 (raw file):

Previously, sumeerbhola wrote…

should this say
// REQUIRES: reqCount > 0

Done.

---

pkg/util/admission/sql_cpu_handle.go line 270 at r3 (raw file):

Previously, sumeerbhola wrote…

If this code is never leaking tokens, it seems unnecessary to have multiple sentences about leaks.
Or at least we should make it clear to the reader that this code doesn't leak, even though small leaks are harmless.

Done.

---

pkg/util/admission/sql_cpu_handle.go line 328 at r3 (raw file):

Previously, sumeerbhola wrote…

error will only happen on context cancellation, iirc. Please confirm.

So this should be handled also by accounting for the deficit without blocking.

Good catch, done.

---

pkg/util/admission/sql_cpu_handle.go line 347 at r3 (raw file):

Previously, sumeerbhola wrote…

This buffer > 0 could be hoisted before calling the preceding closure.

Done.