execinfra

type BatchReceiver interface {

	// PushBatch sends a batch to the consumer of this BatchReceiver. The
	// semantics of the method are exactly the same as of RowReceiver.Push.
	PushBatch(batch coldata.Batch, meta *execinfrapb.ProducerMetadata) ConsumerStatus
	// contains filtered or unexported methods
}

type ConsumerStatus uint32

type Dialer interface {
	DialNoBreaker(context.Context, roachpb.NodeID, rpc.ConnectionClass) (*grpc.ClientConn, error)
}

type DistSQLMetrics struct {
	QueriesActive         *metric.Gauge
	QueriesTotal          *metric.Counter
	ContendedQueriesCount *metric.Counter
	FlowsActive           *metric.Gauge
	FlowsTotal            *metric.Counter
	FlowsQueued           *metric.Gauge
	FlowsScheduled        *metric.Counter
	QueueWaitHist         *metric.Histogram
	MaxBytesHist          *metric.Histogram
	CurBytesCount         *metric.Gauge
	VecOpenFDs            *metric.Gauge
	CurDiskBytesCount     *metric.Gauge
	MaxDiskBytesHist      *metric.Histogram
	QueriesSpilled        *metric.Counter
	SpilledBytesWritten   *metric.Counter
	SpilledBytesRead      *metric.Counter
}

type DoesNotUseTxn interface {
	DoesNotUseTxn() bool
}

type ExecStatsForTraceHijacker interface {
	// HijackExecStatsForTrace returns ExecStatsForTrace function, if set, and
	// sets it to nil. The caller becomes responsible for collecting and
	// propagating the execution statistics.
	HijackExecStatsForTrace() func() *execinfrapb.ComponentStats
}

type FlowCtx struct {
	AmbientContext log.AmbientContext

	Cfg *ServerConfig

	// ID is a unique identifier for a flow.
	ID execinfrapb.FlowID

	// EvalCtx is used by all the processors in the flow to evaluate expressions.
	// Processors that intend to evaluate expressions with this EvalCtx should
	// get a copy with NewEvalCtx instead of storing a pointer to this one
	// directly (since some processor mutate the EvalContext they use).
	//
	// TODO(andrei): Get rid of this field and pass a non-shared EvalContext to
	// cores of the processors that need it.
	EvalCtx *tree.EvalContext

	// The transaction in which kv operations performed by processors in the flow
	// must be performed. Processors in the Flow will use this txn concurrently.
	// This field is generally not nil, except for flows that don't run in a
	// higher-level txn (like backfills).
	Txn *kv.Txn

	// Descriptors is used to look up leased table descriptors and to construct
	// transaction bound TypeResolvers to resolve type references during flow
	// setup. It is not safe for concurrent use and is intended to be used only
	// during flow setup and initialization. The Descriptors object is initialized
	// when the FlowContext is created on the gateway node using the planner's
	// descs.Collection and is created on remote nodes with a new descs.Collection
	// In the latter case, after the flow is complete, all descriptors leased from
	// this object must be released.
	Descriptors *descs.Collection

	// IsDescriptorsCleanupRequired is set if Descriptors needs to release the
	// leases it acquired after the flow is complete.
	IsDescriptorsCleanupRequired bool

	// nodeID is the ID of the node on which the processors using this FlowCtx
	// run.
	NodeID *base.SQLIDContainer

	// TraceKV is true if KV tracing was requested by the session.
	TraceKV bool

	// CollectStats is true if execution stats collection was requested.
	CollectStats bool

	// Local is true if this flow is being run as part of a local-only query.
	Local bool

	// Gateway is true if this flow is being run on the gateway node.
	Gateway bool

	// DiskMonitor is this flow's disk monitor. All disk usage for this flow must
	// be registered through this monitor.
	DiskMonitor *mon.BytesMonitor

	// PreserveFlowSpecs is true when the flow setup code needs to be careful
	// when modifying the specifications of processors.
	PreserveFlowSpecs bool
}

type LocalProcessor interface {
	RowSourcedProcessor
	// InitWithOutput initializes this processor.
	InitWithOutput(flowCtx *FlowCtx, post *execinfrapb.PostProcessSpec, output RowReceiver) error
	// SetInput initializes this LocalProcessor with an input RowSource. Not all
	// LocalProcessors need inputs, but this needs to be called if a
	// LocalProcessor expects to get its data from another RowSource.
	SetInput(ctx context.Context, input RowSource) error
}

type MetadataTestLevel int

type MetadataTestReceiver struct {
	ProcessorBase
	// contains filtered or unexported fields
}

type MetadataTestSender struct {
	ProcessorBase
	// contains filtered or unexported fields
}

type NoMetadataRowSource struct {
	// contains filtered or unexported fields
}

type OpChains []OpNode

type OpNode interface {
	// ChildCount returns the number of children (inputs) of the operator.
	ChildCount(verbose bool) int

	// Child returns the nth child (input) of the operator.
	Child(nth int, verbose bool) OpNode
}

type ProcOutputHelper struct {
	RowAlloc rowenc.EncDatumRowAlloc

	// OutputTypes is the schema of the rows produced by the processor after
	// post-processing (i.e. the rows that are pushed through a router).
	//
	// If renderExprs is set, these types correspond to the types of those
	// expressions.
	// If outputCols is set, these types correspond to the types of
	// those columns.
	// If neither is set, this is the internal schema of the processor.
	OutputTypes []*types.T
	// contains filtered or unexported fields
}

type ProcStateOpts struct {
	// TrailingMetaCallback, if specified, is a callback to be called by
	// moveToTrailingMeta(). See ProcessorBase.TrailingMetaCallback.
	TrailingMetaCallback func() []execinfrapb.ProducerMetadata
	// InputsToDrain, if specified, will be drained by DrainHelper().
	// MoveToDraining() calls ConsumerDone() on them, InternalClose() calls
	// ConsumerClosed() on them.
	InputsToDrain []RowSource
}

type Processor interface {
	// OutputTypes returns the column types of the results (that are to be fed
	// through an output router).
	OutputTypes() []*types.T

	// MustBeStreaming indicates whether this processor is of "streaming" nature
	// and is expected to emit the output one row at a time (in both row-by-row
	// and the vectorized engines).
	MustBeStreaming() bool

	// Run is the main loop of the processor.
	Run(context.Context)
}

type ProcessorBase struct {
	ProcessorBaseNoHelper

	// OutputHelper is used to handle the post-processing spec.
	OutputHelper ProcOutputHelper

	// MemMonitor is the processor's memory monitor.
	MemMonitor *mon.BytesMonitor

	// SemaCtx is used to avoid allocating a new SemaCtx during processor setup.
	SemaCtx tree.SemaContext
}

type ProcessorBaseNoHelper struct {
	ProcessorID int32

	// Output is the consumer of the rows produced by this ProcessorBase. If
	// Output is nil, one can invoke ProcessRow to obtain the post-processed row
	// directly.
	Output RowReceiver

	FlowCtx *FlowCtx

	// EvalCtx is used for expression evaluation. It overrides the one in flowCtx.
	EvalCtx *tree.EvalContext

	// Closed is set by InternalClose(). Once set, the processor's tracing span
	// has been closed.
	Closed bool

	// Ctx and span contain the tracing state while the processor is active
	// (i.e. hasn't been closed). Initialized using flowCtx.Ctx (which should not be otherwise
	// used).
	Ctx context.Context

	State procState

	// ExecStatsForTrace, if set, will be called before getting the trace data from
	// the span and adding the recording to the trailing metadata. The returned
	// ComponentStats are associated with the processor's span. The Component
	// field of the returned stats will be set by the calling code.
	//
	// Can return nil.
	ExecStatsForTrace func() *execinfrapb.ComponentStats
	// contains filtered or unexported fields
}

type ProcessorConstructor func(
	ctx context.Context,
	flowCtx *FlowCtx,
	processorID int32,
	core *execinfrapb.ProcessorCoreUnion,
	post *execinfrapb.PostProcessSpec,
	inputs []RowSource,
	outputs []RowReceiver,
	localProcessors []LocalProcessor,
) (Processor, error)

type Releasable interface {
	// Release allows this object to be returned to a memory pool. Objects must
	// not be used after Release is called.
	Release()
}

type RepeatableRowSource struct {
	// contains filtered or unexported fields
}

type RowChannel struct {

	// The channel on which rows are delivered.
	C <-chan RowChannelMsg
	// contains filtered or unexported fields
}

type RowChannelMsg struct {
	// Only one of these fields will be set.
	Row  rowenc.EncDatumRow
	Meta *execinfrapb.ProducerMetadata
}

type RowReceiver interface {

	// Push sends a record to the consumer of this RowReceiver. Exactly one of the
	// row/meta must be specified (i.e. either row needs to be non-nil or meta
	// needs to be non-Empty()). May block.
	//
	// The return value indicates the current status of the consumer. Depending on
	// it, producers are expected to drain or shut down. In all cases,
	// ProducerDone() needs to be called (after draining is done, if draining was
	// requested).
	//
	// Unless specifically permitted by the underlying implementation, (see
	// copyingRowReceiver, for example), the sender must not modify the row
	// and the metadata after calling this function.
	//
	// After DrainRequested is returned, it is expected that all future calls only
	// carry metadata (however that is not enforced and implementations should be
	// prepared to discard non-metadata rows). If ConsumerClosed is returned,
	// implementations have to ignore further calls to Push() (such calls are
	// allowed because there might be multiple producers for a single RowReceiver
	// and they might not all be aware of the last status returned).
	//
	// Implementations of Push() must be thread-safe.
	Push(row rowenc.EncDatumRow, meta *execinfrapb.ProducerMetadata) ConsumerStatus
	// contains filtered or unexported methods
}

type RowSource interface {
	// OutputTypes returns the schema for the rows in this source.
	OutputTypes() []*types.T

	// Start prepares the RowSource for future Next() calls and takes in the
	// context in which these future calls should operate. Start needs to be
	// called before Next/ConsumerDone/ConsumerClosed.
	//
	// RowSources that consume other RowSources are expected to Start() their
	// inputs.
	//
	// Implementations are expected to hold on to the provided context. They may
	// choose to derive and annotate it (Processors generally do, and the
	// updated context is usually available at ProcessorBase.Ctx).
	Start(context.Context)

	// Next returns the next record from the source. At most one of the return
	// values will be non-empty. Both of them can be empty when the RowSource has
	// been exhausted - no more records are coming and any further method calls
	// will be no-ops.
	//
	// EncDatumRows returned by Next() are only valid until the next call to
	// Next(), although the EncDatums inside them stay valid forever.
	//
	// A ProducerMetadata record may contain an error. In that case, this
	// interface is oblivious about the semantics: implementers may continue
	// returning different rows on future calls, or may return an empty record
	// (thus asking the consumer to stop asking for rows). In particular,
	// implementers are not required to only return metadata records from this
	// point on (which means, for example, that they're not required to
	// automatically ask every producer to drain, in case there's multiple
	// producers). Therefore, consumers need to be aware that some rows might have
	// been skipped in case they continue to consume rows. Usually a consumer
	// should react to an error by calling ConsumerDone(), thus asking the
	// RowSource to drain, and separately discard any future data rows. A consumer
	// receiving an error should also call ConsumerDone() on any other input it
	// has.
	Next() (rowenc.EncDatumRow, *execinfrapb.ProducerMetadata)

	// ConsumerDone lets the source know that we will not need any more data
	// rows. The source is expected to start draining and only send metadata
	// rows. May be called multiple times on a RowSource, even after
	// ConsumerClosed has been called.
	//
	// May block. If the consumer of the source stops consuming rows before
	// Next indicates that there are no more rows, ConsumerDone() and/or
	// ConsumerClosed() must be called; it is a no-op to call these methods after
	// all the rows were consumed (i.e. after Next() returned an empty row).
	ConsumerDone()

	// ConsumerClosed informs the source that the consumer is done and will not
	// make any more calls to Next(). Must only be called once on a given
	// RowSource.
	//
	// Like ConsumerDone(), if the consumer of the source stops consuming rows
	// before Next indicates that there are no more rows, ConsumerDone() and/or
	// ConsumerClosed() must be called; it is a no-op to call these methods after
	// all the rows were consumed (i.e. after Next() returned an empty row).
	//
	// Processors that embed ProcessorBase can delegate the implementation to
	// the latter if they only need to perform trivial cleanup (calling
	// ProcessorBase.InternalClose).
	ConsumerClosed()
}

type RowSourcedProcessor interface {
	RowSource
	Processor
}

type RuntimeStats interface {
	// GetCPUCombinedPercentNorm returns the recent user+system cpu usage,
	// normalized to 0-1 by number of cores.
	GetCPUCombinedPercentNorm() float64
}

type ScanStats struct {
	// NumInterfaceSteps is the number of times the MVCC step function was called
	// to satisfy a scan.
	NumInterfaceSteps uint64
	// NumInternalSteps is the number of times that MVCC step was invoked
	// internally, including to step over internal, uncompacted Pebble versions.
	NumInternalSteps uint64
	// NumInterfaceSeeks is the number of times the MVCC seek function was called
	// to satisfy a scan.
	NumInterfaceSeeks uint64
	// NumInternalSeeks is the number of times that MVCC seek was invoked
	// internally, including to step over internal, uncompacted Pebble versions.
	NumInternalSeeks uint64
}

type ServerConfig struct {
	log.AmbientContext

	Settings     *cluster.Settings
	RuntimeStats RuntimeStats

	ClusterID   *base.ClusterIDContainer
	ClusterName string

	// NodeID is the id of the node on which this Server is running.
	NodeID *base.SQLIDContainer

	// Locality is the locality of the node on which this Server is running.
	Locality roachpb.Locality

	// Codec is capable of encoding and decoding sql table keys.
	Codec keys.SQLCodec

	// DB is a handle to the cluster.
	DB *kv.DB
	// Executor can be used to run "internal queries". Note that Flows also have
	// access to an executor in the EvalContext. That one is "session bound"
	// whereas this one isn't.
	Executor sqlutil.InternalExecutor

	RPCContext   *rpc.Context
	Stopper      *stop.Stopper
	TestingKnobs TestingKnobs

	// ParentMemoryMonitor is normally the root SQL monitor. It should only be
	// used when setting up a server, or in tests.
	ParentMemoryMonitor *mon.BytesMonitor

	// TempStorage is used by some DistSQL processors to store rows when the
	// working set is larger than can be stored in memory.
	TempStorage diskmap.Factory

	// TempStoragePath is the path where the vectorized execution engine should
	// create files using TempFS.
	TempStoragePath string

	// TempFS is used by the vectorized execution engine to store columns when the
	// working set is larger than can be stored in memory.
	TempFS fs.FS

	// VecFDSemaphore is a weighted semaphore that restricts the number of open
	// file descriptors in the vectorized engine.
	VecFDSemaphore semaphore.Semaphore

	// BulkAdder is used by some processors to bulk-ingest data as SSTs.
	BulkAdder kvserverbase.BulkAdderFactory

	// Child monitor of the bulk monitor which will be used to monitor the memory
	// used by the column and index backfillers.
	BackfillerMonitor *mon.BytesMonitor

	// Child monitor of the bulk monitor which will be used to monitor the memory
	// used during backup.
	BackupMonitor *mon.BytesMonitor

	// ParentDiskMonitor is normally the root disk monitor. It should only be used
	// when setting up a server, a child monitor (usually belonging to a sql
	// execution flow), or in tests. It is used to monitor temporary storage disk
	// usage. Actual disk space used will be a small multiple (~1.1) of this
	// because of RocksDB space amplification.
	ParentDiskMonitor *mon.BytesMonitor

	Metrics            *DistSQLMetrics
	RowMetrics         *row.Metrics
	InternalRowMetrics *row.Metrics

	// SQLLivenessReader provides access to reading the liveness of sessions.
	SQLLivenessReader sqlliveness.Reader

	// JobRegistry manages jobs being used by this Server.
	JobRegistry *jobs.Registry

	// LeaseManager is a *lease.Manager. It's stored as an `interface{}` due
	// to package dependency cycles
	LeaseManager interface{}

	// A handle to gossip used to broadcast the node's DistSQL version and
	// draining state.
	Gossip gossip.OptionalGossip

	// Dialer for communication between SQL and KV nodes.
	NodeDialer *nodedialer.Dialer

	// Dialer for communication between SQL nodes/pods.
	PodNodeDialer *nodedialer.Dialer

	// SessionBoundInternalExecutorFactory is used to construct session-bound
	// executors. The idea is that a higher-layer binds some of the arguments
	// required, so that users of ServerConfig don't have to care about them.
	SessionBoundInternalExecutorFactory sqlutil.SessionBoundInternalExecutorFactory

	ExternalStorage        cloud.ExternalStorageFactory
	ExternalStorageFromURI cloud.ExternalStorageFromURIFactory

	// ProtectedTimestampProvider maintains the state of the protected timestamp
	// subsystem. It is queried during the GC process and in the handling of
	// AdminVerifyProtectedTimestampRequest.
	ProtectedTimestampProvider protectedts.Provider

	DistSender *kvcoord.DistSender

	// RangeCache is used by processors that were supposed to have been planned on
	// the leaseholders of the data ranges that they're consuming. These
	// processors query the cache to see if they should communicate updates to the
	// gateway.
	RangeCache *rangecache.RangeCache

	// SQLStatsController is an interface used to reset SQL stats without the need to
	// introduce dependency on the sql package.
	SQLStatsController tree.SQLStatsController

	// IndexUsageStatsController is an interface used to reset index usage stats without
	// the need to introduce dependency on the sql package.
	IndexUsageStatsController tree.IndexUsageStatsController

	// SQLSQLResponseAdmissionQ is the admission queue to use for
	// SQLSQLResponseWork.
	SQLSQLResponseAdmissionQ *admission.WorkQueue

	// CollectionFactory is used to construct descs.Collections.
	CollectionFactory *descs.CollectionFactory
}

type SpansWithCopy struct {
	Spans     roachpb.Spans
	SpansCopy roachpb.Spans
}

type TestingKnobs struct {
	// RunBeforeBackfillChunk is called before executing each chunk of a
	// backfill during a schema change operation. It is called with the
	// current span and returns an error which eventually is returned to the
	// caller of SchemaChanger.exec(). In the case of a column backfill, it is
	// called at the start of the backfill function passed into the transaction
	// executing the chunk.
	RunBeforeBackfillChunk func(sp roachpb.Span) error

	// RunAfterBackfillChunk is called after executing each chunk of a backfill
	// during a schema change operation. In the case of a column backfill, it is
	// called just before returning from the backfill function passed into the
	// transaction executing the chunk. It is always called even when the backfill
	// function returns an error, or if the table has already been dropped.
	RunAfterBackfillChunk func()

	// SerializeIndexBackfillCreationAndIngestion ensures that every index batch
	// created during an index backfill is also ingested before moving on to the
	// next batch or returning.
	// Ingesting does not mean that the index entries are necessarily written to
	// storage but instead that they are buffered in the index backfillers' bulk
	// adder.
	SerializeIndexBackfillCreationAndIngestion chan struct{}

	// IndexBackfillProgressReportInterval is the periodic interval at which the
	// processor pushes the spans for which it has successfully backfilled the
	// indexes.
	IndexBackfillProgressReportInterval time.Duration

	// ForceDiskSpill forces any processors/operators that can fall back to disk
	// to fall back to disk immediately.
	//
	// Cannot be set together with MemoryLimitBytes.
	ForceDiskSpill bool

	// MemoryLimitBytes specifies a maximum amount of working memory that a
	// processor that supports falling back to disk can use. Must be >= 1 to
	// enable. This is a more fine-grained knob than ForceDiskSpill when the
	// available memory needs to be controlled. Once this limit is hit,
	// processors employ their on-disk implementation regardless of applicable
	// cluster settings.
	//
	// Cannot be set together with ForceDiskSpill.
	MemoryLimitBytes int64

	// TableReaderBatchBytesLimit, if not 0, overrides the limit that the
	// TableReader will set on the size of results it wants to get for individual
	// requests.
	TableReaderBatchBytesLimit int64
	// JoinReaderBatchBytesLimit, if not 0, overrides the limit that the
	// joinReader will set on the size of results it wants to get for individual
	// lookup requests.
	JoinReaderBatchBytesLimit int64

	// DrainFast, if enabled, causes the server to not wait for any currently
	// running flows to complete or give a grace period of minFlowDrainWait
	// to incoming flows to register.
	DrainFast bool

	// MetadataTestLevel controls whether or not additional metadata test
	// processors are planned, which send additional "RowNum" metadata that is
	// checked by a test receiver on the gateway.
	MetadataTestLevel MetadataTestLevel

	// Changefeed contains testing knobs specific to the changefeed system.
	Changefeed base.ModuleTestingKnobs

	// Flowinfra contains testing knobs specific to the flowinfra system
	Flowinfra base.ModuleTestingKnobs

	// Forces bulk adder flush every time a KV batch is processed.
	BulkAdderFlushesEveryBatch bool

	// JobsTestingKnobs is jobs infra specific testing knobs.
	JobsTestingKnobs base.ModuleTestingKnobs

	// BackupRestoreTestingKnobs are backup and restore specific testing knobs.
	BackupRestoreTestingKnobs base.ModuleTestingKnobs

	// StreamingTestingKnobs are backup and restore specific testing knobs.
	StreamingTestingKnobs base.ModuleTestingKnobs

	// IndexBackfillMergerTestingKnobs are the index backfill merger specific
	// testing knobs.
	IndexBackfillMergerTestingKnobs base.ModuleTestingKnobs
}