rac2: introduce send token watcher interface

Introduce the `SendTokenWatcher` interface, which will be used to watch
and be notified when there are elastic send tokens available for a
stream. It is intended to be used when a send queue develops and the
caller wishes to be notified of available elastic send tokens, in order
to dequeue and send entries.

Resolves: #128011
Release note: None

pkg/kv/kvserver/kvflowcontrol/rac2/store_stream.go

@@ -10,7 +10,11 @@
 
 package rac2
 
-import "github.com/cockroachdb/cockroach/pkg/kv/kvserver/kvflowcontrol"
+import (
+	"context"
+
+	"github.com/cockroachdb/cockroach/pkg/kv/kvserver/kvflowcontrol"
+)
 
 // StreamTokenCounterProvider is the interface for retrieving token counters
 // for a given stream.
@@ -22,3 +26,36 @@ type StreamTokenCounterProvider interface {
 	// Send returns the send token counter for the given stream.
 	Send(kvflowcontrol.Stream) TokenCounter
 }
+
+// SendTokenWatcherHandleID is a unique identifier for a handle that is
+// watching for available elastic send tokens on a stream.
+type SendTokenWatcherHandleID int64
+
+// SendTokenWatcher is the interface for watching and waiting on available
+// elastic send tokens. The watcher registers a notification, which will be
+// called when elastic tokens are available for the stream this watcher is
+// monitoring. Note only elastic tokens are watched as this is intended to be
+// used when a send queue exists.
+//
+// TODO(kvoli): Consider de-interfacing if not necessary for testing.
+type SendTokenWatcher interface {
+	// NotifyWhenAvailable queues up for elastic tokens for the given send token
+	// counter. When elastic tokens are available, the provided
+	// TokenGrantNotification is called. It is the caller's responsibility to
+	// call CancelHandle when tokens are no longer needed, or when the caller is
+	// done.
+	NotifyWhenAvailable(
+		TokenCounter,
+		TokenGrantNotification,
+	) SendTokenWatcherHandleID
+	// CancelHandle cancels the given handle, stopping it from being notified
+	// when tokens are available. CancelHandle should be called at most once.
+	CancelHandle(SendTokenWatcherHandleID)
+}
+
+// TokenGrantNotification is an interface that is called when tokens are
+// available.
+type TokenGrantNotification interface {
+	// Notify is called when tokens are available to be granted.
+	Notify(context.Context)
+}